Long-running requests

Some operations, such as variable purchases, may not be fullfilled immediately. In those circumstances, the API will instead respond asynchronously.

It does so by providing the response to the original request, using the 303 See Other http status code, at a different URI provided in the location HTTP header. You will need to retrieve the results on that URI using a GET method.

This resource may return any of the following responses:

  • 200: The data is available immediately
  • 202: THe data is not avaiable yet (see below)
  • 400: An unknown client error occured
  • 401: Unauthorized access
  • 422: The request entity was malformed
  • 500: An unknown server error occured
  • 503: The service is unavaiable, for example when a downstream service is closed for the night, or due to server maintenance
  • 504: A service timed-out trying to fullfill the request

If you receive a 202 Accepted, you will try to reload this resource until it is available. The response to that resource will then be the one you would have received had the original request completed synchronously, with a 200 OK meaning you successfully retrieved the data.

Opting-in to asynchronous processing

In order to place orders asynchronously, you will need to advertise the fact that your code supports asynchronuous responses.

This is done by using the prefer header as specified in RFC 7240 – Prefer Header for HTTP, using the the respond-async preference.

Prefer: respond-async

If the header is not present, a 400 Client Error status code will be returned.

Waiting times

During long running flows, the API may provide suggested waiting times that clients are encouraged to respect.

In the case of a 303 See Other response, the waiting time is specified in the retry-after http header, in seconds.

In the folowing example, the server asks the client to wait for 60 seconds.

retry-after: 60

In the case of a 202 Accepted response, the waiting time uses normal HTTP caching freshness rules, as specified in RFC 7234 - Hypertext Transfer Protocol (HTTP/1.1): Caching. For example, a must-revalidate parameter would require the GET to be issued again after the cache has expired, which is defined using the max-age parameter: after 10 seconds, the request should be re-issued as per the example below:

cache-control: private,max-age=10,must-revalidate

A fully asynchronous example

You can issue a purchase request to a dataset.

POST /world/GB-eaw/titles/[TITLE_NUMBER]/catalog HTTP/1.1
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/ld+json
Accept: application/ld+json
Prefer: respond-async

{
  "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
  "@type": "PurchaseVariableAction",
  "variables": [
    "https://api.whenfresh.com/vars/CLS/DDA#Property/Title/Restriction/Property Title has Restrictions"
  ]
}

303 See Other
Location: /purchases/1234
Retry-After: 10
Preference-Applied: respond-async

Wait 10 seconds

GET /purchases/1234
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Accept: application/ld+json

202 Accepted
Content-Length: 0
Cache-Control: private,max-age=10,must-revalidate

Wait 10 seconds

GET /purchases/1234
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Accept: application/ld+json

200 OK
Content-Length: 123

{
    "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
    "@type": "hydra:Collection",
    "manages": {
        "property": "rdf:type",
        "object": "Datum"
    },
    "member": [
        {
            "@type": "https://api.whenfresh.com/ontologies/Property/Title#Restriction/Property Title has Restrictions",
            "price": {
                "value": 1,
                "currency": "GBP"
            },
            "variable": {
                "@type": "Variable",
                "@id": "https://api.whenfresh.com/vars/CLS/DDA#Property/Title/Restriction/Property Title has Restrictions"
            },
            "value": "true"
        }
    ],
    "totalItems": 1
}

Remember to pass the same credentials for all requests.

Testing

In order to ensure good performance, the API will cache data, and you may only get the full long-running flow the first time you purchase data from a resource catalog.

Full flow

To assist in testing the full flow when integrating with the API (303 -> 202 -> 200), even when a resource has already been purchased, you can force the API to bypass the immediate response by adding the whenfresh.min-wait preference, expressed in seconds.

The following example will continue returning a 202 for 60 seconds.

Prefer: respond-async, whenfresh.min-wait=60

This is only available currently for testing the following England and Wales title numbers:

  • P24537
  • SGL118369
  • DN85293
  • NK81339
  • WA555377

Returning immediately from any purchase

It is also possible to send the purchase in a fire and forget manner, and recover the results later, by forcing an immediate return. This is achieved by using the wait preference and setting it to 0, as the following example demonstrates.

Prefer: respond-async, wait=0