Reference guide

We deliver our RESTful APIs using the agile delivery process set out in the GOV.UK Service Manual.

We tag our RESTful APIs with a status to indicate which project phase we are currently in, as follows:

• Alpha - early prototyping - the API specification is available, and maybe a sandbox service is available - but we expect to make extensive breaking changes based on developer feedback
• Beta - the API is more stable, and might even be available for production use, but might still be subject to minor breaking changes
• Stable - the API is live and available for production use
• Deprecated - the API is scheduled to be retired
• Retired - the API is no longer available for use

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:

• 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 limit the number of requests your application can make to our APIs. 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 2 requests per second per application per API. The limit is applied per minute, so you can make up to 120 requests in any given 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.

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 interative product backlog.

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 (i.e. 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.