> ## Documentation Index
> Fetch the complete documentation index at: https://docs.24hourinspections.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Conventions

> A reference for common patterns in payloads and responses.

## Versioning

We support path-based and header-based versioning. In the event that they conflict, path-based versioning will prevail.

<AccordionGroup>
  <Accordion title="Path-Based Versioning" icon="folder-tree">
    ##### Resolves to Version 1 of the route:

    ```BASH
      curl --request GET \
           --url https://api.24hourinspections.com/v1/ping
    ```

    ##### Still resolves to Version 1 of the route:

    ```BASH
      curl --request GET \
          --url https://api.24hourinspections.com/v1/ping \
          --header "Accept: application/json; version=2"
    ```
  </Accordion>

  <Accordion title="Header-Based Versioning" icon="folder-bookmark">
    ##### Resolves to Version 2 of the route

    ```BASH
      curl --request GET \
          --url https://api.24hourinspections.com/ping \
          --header "Accept: application/json; version=2"
    ```
  </Accordion>

  <Accordion title="No Versioning" icon="folder-xmark">
    ##### Resolves to the earliest maintained version. e.g. v1

    ```BASH
      curl --request GET \
          --url https://api.24hourinspections.com/ping
    ```
  </Accordion>
</AccordionGroup>

## Wrapped Responses

All responses return an object with `status`, `code`, and `data` fields. <br />
4xx & 5xx responses also return a `message` field.

<CodeGroup>
  ```JSON 2xx Response Format
  {
    "status": "success",
    "code": 200,
    "data": { ... }
  }
  ```

  ```JSON 4xx & 5xx Response Format
  {
    "code": 400,
    "status": "error",
    "message": "<string>",
    "data": "<string | object | array>"
  }
  ```
</CodeGroup>

## Pagination

All lists are returned as an array of `items`, with a `pagination` object and `_links` that follow the [HAL linking strategy](https://stateless.co/hal_specification.html).

```JSON {5, 9, 15}
{
  "status": "success",
  "code": 200,
  "data": {
    "items": [
      { ... },
      { ... }
    ],
    "pagination": {
      "total_items_count": 29,
      "total_pages": 2,
      "current_page": 1,
      "items_per_page": 20
    },
    "_links": {
      "self": {
        "href": "/v1/orders?page=1&limit=20"
      },
      "first": {
        "href": "/v1/orders?page=1&limit=20"
      },
      "last": {
        "href": "/v1/orders?page=2&limit=20"
      },
      "prev": {
        "href": "/v1/orders?page=1&limit=20"
      },
      "next": {
        "href": "/v1/orders?page=2&limit=20"
      }
    }
  }
}
```

## Query Parameters

All `GET MANY` routes support the following query parameters:

| **Name**  | **Description**                                                                               |
| :-------- | :-------------------------------------------------------------------------------------------- |
| `page`    | The page number you want to retrieve from the paginated results                               |
| `limit`   | The maximum number of records to return per page                                              |
| `q`       | A search term to filter results by matching text                                              |
| `sort`    | A comma-separated list of fields to sort the results by                                       |
| `include` | A urlencoded list of related objects to include with expanded data (defaults to 1 level deep) |
| `filters` | A urlencoded list of field criteria to filter the results by                                  |