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: 8
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.
Latest stable is the current production API: no backwards-incompatible changes (new endpoints and additive fields may still appear). next is the upcoming version — always one ahead of latest stable. Individual endpoint contracts on next may still change. Older frozen versions remain for existing integrations.
Ideally use the latest stable version. Use next only for endpoints where you need a newer contract.
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 |
Optional Fields
- When including optional fields without data, use
null. - In request bodies, an empty string (
"") is treated asnull. Do not send""expecting a distinct empty-string value.