Reference guide

We tag our APIs with a status as follows:

• alpha - early prototyping - the API specification is available, and might be available for testing via a sandbox service or an integration environment - but we expect to make breaking changes based on developer feedback
• private beta - the API is available in production but only to a limited number of connecting applications. It is more stable, but might still be subject to minor breaking changes
• beta (or public beta) - the API is available in production to all comers. It might still be subject to breaking changes
• stable - there will be no breaking changes - if we need to make breaking changes we'll publish a new version of the API
• deprecated - the API is still available and service levels still apply, but we plan to retire it at some point. We are unlikely to make any updates and new integrations are not permitted. Once deprecated, we will consult with developers before deciding on a retirement date
• retired - the API is no longer available for use

For more details on deprecation and retirement, see our deprecation and retirement policy.

In order to keep our API and service estate manageable, we might deprecate and eventually retire an API if:

• we have built a new major version of the API
• we have built a new API that provides equivalent capabilities - such as a FHIR API
• the API is not fit for purpose, for example because it doesn't include important use cases
• the API is not being used or has limited usage
• the API is insecure or a security risk

We appreciate that this might cause inconvenience, but we must use public funds efficiently and cannot afford to maintain replaced or obsolete APIs indefinitely.

If we deprecate an API:

• we will let you know
• the API will still be available for use
• our service levels will still apply
• we are unlikely to make any updates
• we will not permit new integrations - with the exception of in-flight integrations
• we will consult with you on an appropriate date to retire the API

For details on APIs that are currently being considered for deprecation or retirement, see our interactive product backlog.

We use incoming feedback widgets and pop-up polls to collect feedback from you to improve our service, using a product called Hotjar.

Give us feedback by clicking on the blue feedback widget which appears as a tab on the right hand side of many pages. You can rate the page, give specific feedback comments and even select a specific element on the page to leave feedback on. Leave your email address if you're happy for us to contact you about your feedback. If you do not want to leave feedback, click the X to minimize the widget.

Certain pages have pop-up polls with questions about page content. Again, leave your email address if you're happy for us to contact you about your feedback. If you do not want to answer, click the top arrow to minimise the poll.

If you cannot see the feedback widget or pop-up polls

All pages in our developer hub (under the URL https://digital.nhs.uk/developer) should have either a feedback widget or a pop-up poll, but never both.

Some browser privacy settings, or extensions such as pop-up or ad blockers, prevent these tools from appearing or working correctly, so:

• consider whitelisting our website in your blocker software so that you can leave us feedback
• check to see if you have "Do Not Track" set in you browser or a blocking cookie installed on your browser as explained on Hotjar's Do Not Track page

Whatever the case, we'd still like to hear your feedback on our site which you can send by contacting us.

5xx status codes

A 5xx status code means the server has a problem. The most common codes and their meanings are as follows:

We do not currently have an environment you can use for performance testing your integration.

If you need to performance test your integration, we recommend you build stubs to simulate our APIs.

If you think it would make integration easier if we provided a performance test environment, you can can upvote the feature suggestion on our interactive product backlog.

For some of our APIs, we limit the number of transactions you can make per unit of time. This protects our service against excessive use and denial-of-service (DoS) attacks, and is also to encourage you to use our APIs efficiently.

Our standard rate limit for the production environment is 5 requests per second per application per API:

• the limit is applied per minute, so you can make up to 300 requests in any given (rolling) minute
• the limit applies per application, per API
• it only applies to APIs on our API platform - where the domain is https://api.service.nhs.uk
• it does apply to our OAuth 2.0 authorisation service - https://api.service.nhs.uk/oauth.

If you go over the rate limit you'll receive a response with an HTTP status of 429 (Too Many Requests).

Some of our APIs also have global rate limits for additional protection. These should not normally affect you, but in extreme cases you might get a 429 response even if you have not gone over your application's rate limit.

Our path-to-live environments have very low rate limits. They are for functional testing only - you should not use them for performance testing.

If you have problems with rate limits, contact us to discuss your application design and volumetrics, and to see whether it's appropriate to raise your rate limit.

Each of our APIs has a service level which defines how available it is and how quickly we fix issues.

The service level applies to the production environment only, not to our test environments. APIs with an API status of alpha or retired are not available in production and thus do not have a service level defined.

The service levels are as follows:

*Bronze operational hours are a guaranteed minimum, with many APIs being available outside of business hours.

To find out the service level for a given API, see the API specification in our API catalogue.

All of our RESTful APIs have only a single version, and you do not need to specify the version number when you call the API.

Once an API is stable (meaning it has exited beta) we avoid making any breaking changes. That means we might add new data fields or add new valid values to code sets, but we won't remove any mandatory fields or change the semantic meaning of any existing fields or code sets.

If we ever do need to make breaking changes to a stable API, we will use HTTP headers to allow you to specify the API version you want to call. We'll do this in a backwards-compatible way.