Asynchronous responses

The majority of responses are asynchronous. This design decision was made to reduce the probability of losing a response (e.g due to network timeout).

For an async response, the initial response will look something like:

{
    "asyncOperation": {
        "token": "a3759997-310d-4513-8d2a-9e047e58368f",
        "status": "IN_PROGRESS"
    }
}

You then use the token to poll via GETing the /poll subpath for the relevant API method.

E.g POST /heldTicket/quote → issued token in response → poll with token GET /heldTicket/quote/poll?asyncOperationToken=xxx

You then continue polling with the aim of receiving asyncOperation.status=READY.

Possible polling outcomes

• asyncOperation.status=IN_PROGRESS
  • Keep polling
• asyncOperation.status=EXPIRED
  • The request/response timed out and is lost, see later section on resolution if request/response was critical
• asyncOperation.status=NOT_FOUND
  • Either the token is invalid (e.g malformed) or the request/response timed out and is lost, see later section on resolution if request/response was critical
• asyncOperation.status=READY
  • Proceed to read result object, see later section
• A 4xx HTTP error
  • Something is invalid with your request
• You decide to give up on polling after some time
  • Response is lost, see later section on resolution if request/response was critical
• Any other response / no response
  • Consider trying to poll again
  • Response is lost, see later section on resolution if request/response was critical

Lost responses

If a response is lost you won’t know the outcome so consider the impact of this. In particular for an /execute you won’t know the outcome of the transaction and you will need to resolve this yourself. E.g you may need to investigate “did my request to purchase a seat succeed?”.

asyncOperation.status=READY

A ready response will look something like this:

{
    "asyncOperation": {
        "token": "a3759997-310d-4513-8d2a-9e047e58368f",
        "status": "READY"
    },
    "result": {
        ...
    }
}

Where result contains the response to your original request