API concepts

Clients

A client represents a consumer of the API. Typically, this will be an application or an instance of an application. Clients are identified via the Connect API token which is provided in each header request. Additional security can be configured against clients to restrict certain functionality as appropriate. The client identity is passed from Connect to downstream Vista services affecting downstream behaviour and allowing per-client reporting.

User sessions

A user session represents a series of requests between a client and the API. This session is defined by the client, and is represented by a user session ID string that is provided to the API to link subsequent calls together. The client can end and begin a new session by simply sending a new user session ID. A user session can have up to one order and up to one Loyalty Session associated with it at any one time.

Loyalty sessions

A Loyalty session represents a single logged in Loyalty member and the actions they carry out through the Connect API, allowing access to member-specific functionality. A Loyalty session can be linked to a user session or be independent of the user session whereby subsequent user session calls will be under the context of the signed-in member, or independently by using a dedicated Loyalty Session token.

Orders

The main purpose of the Connect API is to make Vista orders. Connect treats orders much like a standard shopping cart in that items can be added, removed, or modified within the order, followed by a payment/check-out style process. While Connect orders can include multiple tickets and concessions, it can only contain items from a single cinema site.

Bookings

Once an order has been completed it becomes a booking. While bookings cannot be amended directly at present - they can be searched, refunded and converted from an unpaid booking to a paid booking.

Tenants

Each cinema circuit typically hosts its own instance of Connect. However, it is possible for Connect to be deployed in a multi-tenanted environment. In a multi-tenanted environment, multiple cinema circuits are being serviced by a single Connect API. In this case, each client must provide a tenant ID with each call to indicate which circuit they wish to interact with. For a single-tenant, environment no tenant ID is required.