Making requests to the Xure API

The Xure API follows REST principles. That is to say, each collection or item of data accessible via the API has it's own unique URL. To obtain data, simply issue a request to the URL (known as an API endpoint) specifying the format in which you wish to receive the response. You can test this out in your browser whilst browsing through the public API endpoints.

You'll need to add a few HTTP headers to every request to authorise your access; specify your desired data format and utilise your own request quota. These headers and processes are outlined below.

Authorising your access

Most of the Xure API methods give access to secure data and therefore require you to provide some form of authorisation with a request. Generally, this is through provision of a bearer token in the headers of your request.

Tokens are obtained by calling the Authenticate method with a username and password. The token should be included in the Authorization header sent with every further request:

Authorization: Bearer [token]

Authorization header format

If it is not possible to alter the headers for the request, the token may be sent as a form or query string parameter with the key 'access_token'. It is not recommended to send the token as part of the query string for security reasons as it may be cached by proxy servers or recorded in server log files.

Once issued, tokens are then valid for a period of thirty days.

Authorisation failures

An incorrectly formatted authorization header will result in a Bad Request (400) HTTP error being returned by the server. If the token is invalid, expired or not recognized an Unauthorised (401) HTTP error is returned. Your application should gracefully handle these by getting the user to re-authenticate in order to obtain a fresh token.

Where calls to API methods fail due to the user having insufficient permissions to access the requested data or method, a Not Permitted (403) HTTP error will be returned if a valid token was supplied, or an Unauthorized (401) HTTP error if authentication is required.

Negotiating request and response formats

Generally, Xure API methods support data being received in URL encoded, XML or JSON formats with responses being returned in either XML or JSON format.

The appropriate format to use is determined by examining the Accept and Content-Type headers sent with the HTTP request. This process is called content negotiation. Callers should set these headers to correctly describe the format of the data being sent, and to negotiate the format of data to be received in return.
 

POST https://api.xure.co/v1/authenticate.eb HTTP/1.1
Content-Type: application/www-form-urlencoded
Accept: application/json

Sample headers sent with a request containing a url-encoded form post and requesting the response in JSON format

The content negotiation process can be overridden by adding a '$format' parameter to the query string component of the URL with the value of either 'XML' or 'JSON'.

Commonly-used MIME types

The table below describes MIME types in common use that are recognised by the API during the content negotiation process:

Specific API methods may support alternative formats (such as CSV data). The documentation for each method describes the full range of formats and mime types permitted for that method. 

Request quota limits

All calls to the Xure API are subject to quota limits. Applications that make requests too frequently will reach the quota limit, with further requests receiving a Too Many Requests (429) HTTP error until quota restrictions are automatically lifted at the end of the quota measurement period.

Quotas are measured in one of two ways:

• If no API key is supplied with the request, the client IP address is assigned a default quota. This is currently set at 500 requests per hour.
• If an API key is provided with the request, the hourly quota allocated to the application developer is used, This quota applies to all clients utilising the same key, regardless of their IP address.

In both cases, the quota measurement period is set as an hour from the point at which a request is first received that consumes one of the two quota limits. The period is then reset hourly and if no further requests are received against a quota for over an hour, the measurement period recommences at the point the next request is received.

HTTP headers are included with a response that detail the current quota restrictions:

Applying for an API key

If you are developing an application or completing a system integration that is likely to submit a high volume of requests to the Xure API within a short period, please contact us to obtain your own API key and discuss a suitable request quota.

Once you have received your API key, submit this in the X-API-Key header with every request:

X-API-Key: [key]

API Key header format

All API requests are logged and monitored and we reserve the right to take measures against users whose activity causes the service to become degraded. This may include revokation of API keys or a reduction of the request quota allocated to an application.