# Conventions

The Integration Platform APIs follow industry standards for *Restful* API design wherever possible.

## Common properties and parameters

Request parameters

- `pageSize` specifies number of results to be included in each results page. Unless otherwise specified, the `pageSize`
value must be between 1,000 to 100,000 and default to 2,000 when skipped or if `null` was provided.
- `cursor` is used to navigate to the next page by passing in the `nextPageCursor` from previous request (see below).


Response properties

- `nextPageCursor` is returned when the response contains more results than what was specified in the `pageSize`.


## Common HTTP headers

Request headers

- `correlationid` is used to simplify diagnostic problems. When possible, clients should always include a `correlationid` HTTP header when sending requests.


Response headers

- `vista-trace-id` is generated by the Integration Platform.
- `vista-correlation-id` will have the value of the original `correlationid` request header if provided, otherwise it will be generated by the Integration Platform.
- `retry-after` indicates the number of seconds to wait before retrying (see [rate limiting](/integration-platform/getting-started/rate-limiting)).


## Content types

Request body content should have a `Content-Type` of `application/json`.

```shell
curl --location 'https://integration.app.vista.co/api/v1/film-management/films?startDateTime=2024-01-01T00%3A00%3A00Z' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1Ni...
```

## Date formats

- Dates are serialised using the standard `ISO 8601` format.
- Dates may or may not return time zone information depending on the purpose of the date.
- Time zone offsets are returned where the time zone itself is relevant, otherwise dates are returned in UTC time.


| Scenario | Date Type | Example Date |
|  --- | --- | --- |
| Film release date | Business Day | 2014-01-17 |
| Showtime start time | Time zone relevant instant | 2023-10-25T17:45:00+13:00 |
| Order expiry date | Time zone agnostic instant | 2023-10-25T03:36:31+00:00 |


## HTTP response codes

| Code | Name | Details |
|  --- | --- | --- |
| 400 | Bad Request | The request contains invalid data and/or conflicts with a business rule. |
| 401 | Unauthorized | Request has not been authenticated. |
| 403 | Forbidden | Identity of request does not have access to requested endpoint/functionality. |
| 404 | Not Found | The requested resource on the URL has not been found. |
| 429 | Too Many Requests | Rate limit exceeded for request. |
| 500 | Internal Server Error | An unexpected exception has occurred within API application. |
| 502 | Bad Gateway | A downstream call from the API has failed unexpectedly. |
| 504 | Gateway Timeout | A downstream call from the API has timed out. |


## Errors

Errors returned from the API follow the [Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) standard. e.g.

```json
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "detail": "An attempt was made to call the API but 1 validation error occurred.",
    "instance": "/api/v1/film-management/films",
    "traceId": "00-2857e95315f8ba24cd57202b749f2b1a-697f80c46c0d79ae-01",
    "errors": {
        "InvalidParameter": [
            "Request page size must not be a negative."
        ]
    }
    ...
}
```

NOTE
When reporting errors, please ensure you also provide the response header values `vista-correlation-id` and `vista-trace-id`.