Conventions

The Omni-Channel API (OCAPI) follows industry standards for Restful API design wherever possible.

Content types

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

curl 'https://[tenantId]-digital-api.app.vista.co/ocapi/v1/sites' \
--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.

Polymorphism

• Both request and response entities may make use of polymorphism as defined by the Open API 3 specification.
• Polymorphic entities define a type property which is used as a discriminator allowing the serialiser to deserialise the JSON into the appropriate type.

Example of a Standard-type order response.

{
  "order": {
    "id": "90df4170fe594ad1aff03be6b55cb3e4",
    "type": "Standard",
    "showtimes": [
      {
        "showtimeId": "0000000003-4419",
        "tickets": [
          {
            "type": "Normal",
            "ticketTypeId": "0000000003-0022",
            "price": {
              "valueIncludingTax": 19.5,
              "valueExcludingTax": 16.24,
              "tax": 3.26
            }
          }
        ]
      }
    ]
  }
}

Example of a Subscription-type order response.

{
  "order": {
    "id": "90df4170fe594ad1aff03be6b55cb3e4",
    "type": "Subscription",
    "subscription": {
      "subscriptionId": "HO3412",
      "subscriptionBillingOptionId": "B281",
      "price": {
        "valueIncludingTax": 100.0,
        "valueExcludingTax": 85.0,
        "tax": 15.0
      }
    }
  }
}

HTTP response codes

Errors

Errors returned from the API follow the Problem Details standard which should include the key information about the error.

{
  "correlationId": "Vista.Connect.WSVistaWebClient-CONMT1-eZdWERGRU0Sb7LfeFMSjBw--clhPuUs_kaw8UwLTX_Y-Q",
  "originalRequestUrl": "/ocapi/v1/orders/standard/booking",
  "type": null,
  "status": 401,
  "title": "Authentication Token Failed",
  "detail": "No Client exists for supplied global authentication JWT.",
  "instance": null
}

404 errors

Typically a 404 indicates the data identified by the URL is not found.

• This is an expected response code for certain endpoints and represents an error in others.
• Identifiers sent as part of a request body JSON that cannot be found will typically result in a 400 response.

400 errors

Each endpoint may define extended error details for 400 responses including data such as a custom errorCode which allows clients to programmatically handle different error scenarios.

Example below is of a request failing due to requested seats no longer being available. Clients should expect and handle the errorCode 10000 in this case.

{
  "errorCode": 10000,
  "correlationId": "Vista.Connect.WSVistaWebClient-MANUALROB-3204608579a641b086af47c29f43bc30-5o0WeZN3pUGLxuk1Adx3rw",
  "originalRequestUrl": "/ocapi/v1/orders/3204608579a641b086af47c29f43bc30/showtimes/0000000003-4419",
  "type": null,
  "status": 400,
  "title": "Seats unavailable",
  "detail": "Requested seats are sold, currently reserved or unavailable for sale.",
  "instance": null
}

5XX errors

500,502 and 504indicate that an unexpected failure occurred.

• Clients are not expected to handle these status codes specifically. Any returned data is purely for diagnostic and auditing purposes.
• If possible, client applications should log correlationId when logging unexpected responses from the API as this value can be used to correlate logs throughout the Vista suite for troubleshooting purposes.