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
• 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.

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.