Skip to main content

Reference guide

This is a reference to some of how we build our APIs. You may also find other useful information in our A-Z glossary.

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
  • Live (no tag) - the API is stable and available for production use
  • Deprecated - the API is scheduled to be retired
  • Retired (not visible) - 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:

HTTP code Error message Meaning
500 INTERNAL_SERVER_ERROR The server does not know how to handle the request.
501 NOT_IMPLEMENTED The server does not support the request method, which it cannot handle. (The only methods that servers are required to support are GET and HEAD.)
502 BAD_GATEWAY The server got an invalid response, while working as a gateway or proxy to another server.
503 SERVICE_UNAVAILABLE The server cannot handle the request because it is down for maintenance or overloaded.
504 GATEWAY_TIMEOUT The server did not get a response in time, while working as a gateway or proxy to another server.

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.

Last edited: 14 October 2020 4:20 pm