• Documentation
• Application naming guidelines
• Reference guide
  • API access
  • Browser support for OAuth 2.0
  • Cross-origin resource sharing (CORS)
  • HTTP redirection
  • Rate limiting
  • Redirect URIs
  • Scopes
  • TLS standards
• Authorisation
• Sample project
• Terms of use

Reference guide

Warning Currently you can only integrate with our sandbox environment. Production integration will be possible when the APIs have reached Beta

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.

If you are using the Microsoft Web Browser Control embedded browser for the authorisation journey, be aware that by default this will operate in IE7 compatibility mode which we do not formally support. For details of one way to handle this, see Controlling WebBrowser Control Compatibility (opens in a new tab).

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

Examples of valid (and invalid) redirect URIs

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.