# General

General features and requirements for API end points 

## Version

All API end points will require an Accept-Version in the request header.
Failure to provide the header will return a status code of `400`, however, an invalid version can return a `404` or `400`.

`Accept-Version: 1`

In general all changes to this API will be made in a non-breaking manner (fields added, but not removed).
However, if breaking changes are required the version number will be incremented.
The old version will be maintained for up to 12 months before being removed, or if no use is detected over 30 continuous days.

:::warning
Fields or functionality not documented here may be removed or modified at anytime without version change or notice.
:::

## Tenant

All API end points, except for authentication, will be within the context of a tenant identified by a unique identifier (UUID)

### Request

`GET https://api.cartoncloud.com/tenants/{tenantId}/api_endpoint`

| URL Parameter | Description                            |
|---------------|----------------------------------------|
| `tenantId`    | The UUID for the tenant to be accessed |

## Pagination

For search requests and other end points which return multiple elements, data will be paged and the headers below returned.

Pagination uses the number of line items per page, specified using pageSize.

### Request

`GET https://api.cartoncloud.com/tenants/{tenantId}/api_endpoint?page=5&size=20`

| Query Parameter | Description                           | Default               |
|-----------------|---------------------------------------|-----------------------|
| `page`          | The page number to return results for | `1`                   |
| `size`          | The number of elements per page       | varies with end point |

### Response

| Header           | Description                                                             |
|------------------|-------------------------------------------------------------------------|
| `Total-Pages`    | Total number of pages of data that is available for the request         |
| `Page-Size`      | The number of elements per page                                         |
| `Page-Number`    | The page number for the returned results                                |
| `Total-Elements` | The total number of elements that is available for the request          |
| `Link`           | Links to other pages as [Web Links](https://tools.ietf.org/html/rfc5988) |

## Optional Fields

- When including optional fields without data, use `null`.
- Do not use an empty string (`""`) as a substitute for `null`. Empty strings are used to represent a valid, empty string value.