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).

Content types

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

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.

HTTP response codes

Errors

Errors returned from the API follow the Problem Details standard. e.g.

{
    "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."
        ]
    }
    ...
}