Reference guide

See Statuses.

APIs

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.

Standards

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

• the standard is no longer is use
• the standard is in use but is no longer strategic
• the standard has been replaced by a newer standard

If we deprecate an API standard:

• we will tag the standard as deprecated in the NHS Data Standards Directory
• we will announce the deprecation to everyone with a developer account
• we will set a retirement date as 12 months from the date of deprecation
• the API standard will still be available for use

If we retire an API standard:

• we will tag the standard as retired in the NHS Data Standards Directory
• we will announce the retirement to everyone with a developer account
• we will archive the standard
• we will discourage from further use

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

Until recently, we used incoming feedback widgets and pop-up polls to collect feedback from you to improve our service.
We're currently looking for a replacement for this functionality.

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

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

• 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
• 400 to 499 if it failed because of a client error by your application
• 500 to 599 if it failed because of an error on our server

For details of specific 2xx and 4xx responses for a specific API, see its API specification.

We do not list specific 5xx responses in API specifications - rather, you should code your application to handle all 5xx responses equally.

4xx status codes

A 4xx status code means there was a problem with the client request to the API. The most common error codes and their meanings are as follows:

5xx status codes

A 5xx status code means there was a problem with the server responding to the API request. The most common error codes and their meanings are as follows:

Our API catalogue contains an increasing number of APIs not created by us at NHS Digital but by associated organisations. These include other parts of the NHS and various partner organisations. Use the API catalogue 'owner' filter to see these APIs.

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.

See also response times.

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.

We do not have formal service level agreements (SLAs) for API response times.

That said, we do monitor response times and react where we believe them to be unreasonable.

As a general guide, you can assume that all our APIs respond in under 0.5 seconds for 95% of the time, unless otherwise stated in the API documentation. In other words they are 'fast enough' for a standard use case where an end user is present. Most of our APIs are much, much faster than that.

This applies to the production environment only - response times might be different (faster or slower) in test environments.

If you want to discuss response times for a particular use case - for example if you need to make multiple API calls and want to be sure the end-to-end response time will be acceptable, contact us.

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

The service level does not cover API response times.

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.

Whilst we expect to meet these service levels, they are not guaranteed, and we will not be liable to you if we do not meet them.

The service levels are as follows:

* Silver Plus we respond to severity 1 and severity 2 incidents outside of business hours (8am to 6pm Monday to Friday excluding Bank Holidays).

** Bronze operational hours are an expected 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.

APIs, message integrations and publish-subscribe events

We tag our APIs, message integrations and publish-subscribe events with a status as follows:

• In development - early prototyping - the API 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
• Beta - the API is available in production - it might still be subject to breaking changes - and its service level can be anything from bronze to platinum
• In production - once out of beta, there will be no breaking changes - if we need to make breaking changes, we'll publish a new version of the API
• Internal - the API is not currently available for integration by external third parties - if you still want to use it, contact us
• Under review for deprecation - the API is under review and we're considering deprecating it - if you have any concerns, contact us
• 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

API standards

We tag our API standards with a status as follows:

• Draft - is still being developed or waiting for assurance or endorsement by qualified bodies
• Active - is stable, maintained and has been assured or endorsed for use by qualified bodies
• Under review for deprecation - is under review and we're considering deprecating it - if you have any concerns, contact us
• Deprecated - is an older version of a standard which is being phased out
• Retired - is not being maintained and should not be used

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

We align these API standard statuses with those found in the NHS Data Standards Directory.

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.