API conventions

A quick glance at the API conventions for V1 and V2 indicate the differences between the two APIs. More detailed information on standards is found below the comparison.

A quick comparison of V1 and V2

Convention	API V1	API V2
JSON casing	PascalCase	camelCase
Error handling	Response code in body	HTTP status code

Dates

Connect API JSON dates are serialized in the ISO 8601 format

2018-01-09T06:35:00.0000000+13:00

Dates where readability is useful are returned with the appropriate offset. These are common for scheduled dates such as a session start time. An 8.05 pm showing is returned as

2018-01-09T20:05:00.0000000+10:00

where the 10:00 represents the time zone offset for the cinema in question.

Certain dates such as last-modified or expiry dates are returned as UTC and will have an appropriate UTC parameter suffix.

2017-11-20T03:58:10.5902928Z

V1 end-points still return and consume dates in the legacy Microsoft JSON Date Format

/Date(1511150290590+1300)/

There should be an ISO 8601 alternative to this date format available on response entities to aid in migration to the more accepted standard.

Requests to V1 end-points in versions prior to 5.0.1 must use the legacy date format. Later versions accept both the legacy date format and ISO format.

Currencies

Connect only supports currencies with two decimal places, any fractional monetary value with higher precision will be rounded to the nearest hundredth.

Error handling and response codes

V1 and V2 end-points differ on error handling significantly. The following sections describe the general error handling behaviour for each of these APIs. For details on per end-point response codes, see the API reference.

V1 error handling

V1 end-points return an HTTP 200 response code for both successful and unsuccessful calls. Clients should inspect the result code in the response body to indicate that the call was unsuccessful. A result code 0 will always indicate a successful call however each end-point may also return specific response codes for partial-success and error scenarios.

{
    "Result": 1,
    "ExtendedResultCode": 50,
    "ErrorDescription": "Session 2549 not found for Cinema 0002"
}

V1 Response Property	Description
Result	Result code for request
ExtendedResultCode	Extended result code, can provide additional information in addition to the Result
ErrorDescription	Textual description of error appropriate for development trouble-shooting

Details of response code can be found in relevant API Reference Section or in the Response Codes reference.

V1 authentication and authorization error handling

V1 end-points return an HTTP 401 response code for unauthenticated requests.

{
    "errorCode": "InvalidLoyaltyToken",
    "errors": [
        {
            "description": "loyaltySessionToken is invalid."
        }
    ]
}

Possible HTTP 401 Error Codes:

Error code	Description
InvalidConnectApiToken	Invalid connectApiToken
InvalidTenantToken	Invalid vista-tenant header (Veezi only)
InvalidLoyaltyToken	Invalid loyaltySessionToken

V1 end-points return an HTTP 403 response code for unauthorized requests.

V2 error handling

V2 end-points follow the standard REST-style HTTP status code responses.

HTTP Status Code	Result
200-299	Success
400	An expected error occurred due to an invalid request
401	Unable to authenticate client (either connectApiToken or loyaltySessionToken or vista-tenant)
403	Permission to end-point or requested behaviour is denied
404	A requested resource (most often part of the URL), such as a cinema or order, was not found
500	An unexpected error occurred. Please consult Connect administrator for further diagnosis

HTTP 400 errors will potentially return an errorCode which may be useful for client-side error handling logic:

{
    "errorCode": "100",
    "errors": [
        {
            "description": "Booking with id WH425CM at cinema 0000000001 is already cancelled or fully refunded"
        }
    ]
}

HTTP 401 errors indicate that the supplied authentication tokens are not valid

{
    "errorCode": "InvalidLoyaltyToken",
    "errors": [
        {
            "description": "loyaltySessionToken is invalid."
        }
    ]
}

Possible HTTP 401 Error Codes:

Error code	Description
InvalidConnectApiToken	Invalid connectApiToken
InvalidTenantToken	Invalid vista-tenant header (Veezi only)
InvalidLoyaltyToken	Invalid loyaltySessionToken

HTTP 403 errors indicate that the supplied Connect API token is valid but does not have permissions to access the requested endpoint/behaviour

{
    "errorCode": "ExpiredLoyaltyToken",
    "errors": [
        {
            "description": "loyaltySessionToken is expired."
        }
    ]
}

errorCode is either empty or ExpiredLoyaltyToken for 403 responses at this moment.

HTTP 404 errors indicate that a requested resource can not be found and will return an errorCode specifying which resource was missing.

{
    "errorCode": "CinemaNotFound",
    "errors": [
        {
            "description": "Cinema 1234 was not found"
        }
    ]
}

Refer to the specific V2 Reference Section for a list of error codes returned by each end-point.

V2 success codes

Clients should check for HTTP status codes in the 200s when calling V2 API end-points and never check specific codes such as 200 and 204 as the specific code returned may change over time.

OData conventions

OData 2.0 standard is used. You can find more details here https://www.odata.org/documentation/odata-version-2-0/

OData error handling

HTTP 401 errors indicate that the supplied authentication tokens are not valid

{
    "odata.error": {
        "code": "InvalidLoyaltyToken",
        "message": {
            "lang": "en-US",
            "value": "loyaltySessionToken is invalid."
        }
    }
}

Possible HTTP 401 Error Codes:

Error code	Description
InvalidConnectApiToken	Invalid connectApiToken
InvalidTenantToken	Invalid vista-tenant header (Veezi only)
InvalidLoyaltyToken	Invalid loyaltySessionToken

Note that code property is a string, while it is an integer for V1 and V2 endpoints.

HTTP 403 errors indicate that the supplied Connect API token is valid but does not have permissions to access the requested endpoint/behaviour

{
    "odata.error": {
        "code": "ExpiredLoyaltyToken",
        "message": {
            "lang": "en-US",
            "value": "loyaltySessionToken is expired"
        }
    }
}

Code is either empty or ExpiredLoyaltyToken for 403 responses at this moment.