Reference guide
Read the reference guide for actions you need to take to make sure your application integrates with Defra.
API access
The base URL for sandbox APIs is:
https://gateway.trade.defra.gov.uk/api/uat
The base URL for production APIs is:
https://gateway.trade.defra.gov.uk/api
Browser support for OAuth 2.0
The OAuth 2.0 authorisation journey is designed to work with most modern browsers as per the list specified on Designing for different browsers and devices, including mobile devices and tablets.
Cross-origin resource sharing (CORS)
The API Platform does not support cross-origin resource sharing (CORS) (opens in a new tab). It is therefore not possible to call our APIs from client-side code within a web browser, for example using Ajax.
HTTP redirection
Our API Platform uses HTTP redirection if endpoints move permanently or temporarily.
Redirection responses have a Location header with the endpoint's new URI.
Rate limiting
We limit the number of requests each application can make. This protects our service against excessive use and Denial-of-Service attacks, and also encourages you to use our APIs efficiently.
We set limits based on anticipated loads and peaks. Our standard limit is 5 requests per second per application.
If you reach this limit you’ll get a response with an HTTP status of 429 (Too Many Requests). If a 429 response is received we recommend that your code should stop making additional API requests for a short period of time before retrying.
Our rate limits are designed to encourage real-time interactions. As such we advise software developers to avoid batching requests if they wish to avoid being rate limited.
If you continually hit this rate limit, contact us to discuss your application design and whether it’s appropriate to raise your rate limit.
Redirect URIs
We use redirect URIs to send the user back to your application after successful (or unsuccessful) authorisation, prior to your application accessing user-restricted endpoints.
You must specify one or more redirect URIs when you create your application, and also specify one redirect URI when you send your user to our authorisation endpoint.
To protect your application from phishing attacks, the redirect URI you use for authorisation (in your call to /oauth/authorize) must match one of those you specified when you created your application.
Also, you must use the same redirect URI when exchanging your authorisation code for an access token (in your call to /oauth/token) that you used for authorisation (in your call to /oauth/authorize).
You can specify a maximum of five redirect URIs.
Examples
Redirect URI | Comments |
---|---|
https://www.example.com/auth-redirect | Valid - when creating your application, you can use the full redirect URI or a partial URI, for example: https://www.example.com/auth-redirect https://www.example.com When calling our authorisation endpoint, your redirect URI must be percent-encoded, for example: https%3A%2F%2Fwww.example.com%2Fauth-redirect |
https://www.example.com:8080/auth-redirect | Valid - includes a port number |
http://www.example.com:8080/auth-redirect | Invalid - uses HTTP, not HTTPS (HTTP is OK for installed applications - see example below) |
/auth-redirect | Invalid - is a relative URI, not an absolute URI |
https://203.0.113.11/auth-redirect | Invalid - uses an IP address, not a DNS name |
https://www.example.com:8080/auth-redirect?some_parameter=some_value | Valid - includes a query component |
https://www.example.com:8080/auth-redirect#some_fragment | Invalid - includes a fragment component |
http://localhost:8080 | Valid - as explained in OAuth 2.0 for installed applications |
urn:ietf:wg:oauth:2.0:oob | Valid - as explained in OAuth 2.0 for installed applications |
urn:ietf:wg:oauth:2.0:oob:auto | Valid - as explained in OAuth 2.0 for installed applications |
Scopes
We use the OAuth 2.0 framework to manage and grant scope based roles to users during the authorisation process to allow communication with our APIs.
For details about authorisation, see this guide topic.
TLS standards
Defra APIs are only accessible over Transport Layer Security (TLS). For example, URLs that begin with https://.
Applications must support TLS 1.2 or higher to avoid known weaknesses in previous versions.