Connect API - version 5.0.10.43 - e0fd2903494d1ae48bab731f3fa0ca8dde49253c

Getting started

The Connect API is a JSON-based web service and as such is easy to get up and running. The API is quite old however and has a few quirks that should be understood before embarking on building your client.

Security

Each request to the Connect API requires a Connect API token to be passed in the HTTP header. These tokens are created and managed by the administrators of the Connect deployment, and will give the calling application a specific set of permissions within the API. Please consult with your token provider to find out what permissions/behaviours have been set in order avoid potential confusion during development.

HTTP Header Description Example Required
connectApiToken Individual token to identify the calling application 591179922C4E42CB9AAE06F3FC6AC13C Always

Multi-tenancy

If you are integrating with a Connect instance that's deployed in a multi-tenanted configuration, you will also need to provide a tenant ID in the HTTP header. This indicates which circuit (tenant) you wish to interact with, and will provide additional client/circuit authorization. This tenant ID should be provided at the same time as your Connect API token if required.

HTTP Header Description Example Required
tenantId ID of the tenant the request is intended for tenant-abc-cinemas Multi-tenancy environment only

Logging

Connect API requests may include a correlation ID (correlationId) in the header, which is used to correlate log entries in different Vista application log files to help identify the source of a request.

The correlationId will either be passed into a Connect API request via the request header, or automatically generated by Connect if no ID is passed in the request. When developing against Connect, sending a correlationId via the request header will allow actions made in an application to be related to logged events in Connect and other downstream Vista products.

Note: Correlation IDs are only logged in Vista applications on version 5.0.2 or later. Applications on earlier versions will not log this information.

HTTP Header Description Example Required
correlationId Identifies the source of a request Connect-VDT002-abcd1234-nbeb2453 Optional

API V1 and API V2

The Connect API comprises of two APIs which differ in the API conventions and styles that they use.

API V1 is the original and currently most feature-rich API. Its style has its origins rooted in SOAP-based RPC style APIs, and has become technically out-of-favour and overly complex.

API V2 is the newer API, which incorporates modern API styles and conventions. The goal for the V2 API is for it to become a complete, better, replacement of V1 in time.

Having two different APIs is not ideal. However, we decided it was preferable to have a V2 API instead of extending the styles and practices of V1 further. We understand this adds some additional overhead and complexity to client development, but this should only be temporary until V2 reaches feature-parity with V1.

OCAPI

OCAPI endpoints are Connect's implementation of an evolving Vista-wide standard for sales APIs. As it evolves it may supersede V1 and V2 endpoints and become a true V3 however it currently has a severely reduced feature set compared to V1 and V2.

Next steps