Skip to main content
Creating a new NHS England: Health Education England, NHS Digital and NHS England have merged. More about the merger.

API policies and best practice

Our policies and best practice guidance for building good quality, easy to use healthcare APIs.


Our mission for API management is to make integration easier.

To support this mission, we've defined a set of policies and best practice guidance for building our APIs.

By doing this, we hope to ensure that the APIs we offer provide a consistent user experience and give API consumers confidence that they are built to a high quality.

All our new and existing APIs must either comply with these policies or else provide a good reason why they have not. 

Our API policies are based on:

We have focussed on policies that are specific to APIs. We have not included policies which apply more generally to all digital services, such as clinical safety, information governance, security and the software engineering quality framework.

For some of our older APIs, it might be difficult to comply with some of the policies. In this case the approach should be to:

  • build a new API that does comply with the policies

  • deprecate and eventually retire the old API, as per our API sunsetting policy

1: API first

All our digital healthcare services must: 

  • provide APIs as the main way of accessing the service's data and business logic 

  • make those APIs available for third party use 

  • consume those APIs in our own front-end applications, sometimes referred to as 'eating your own dog food' 

'API first' is all about putting APIs front and centre of our digital healthcare services.

The functions and capabilities we can provide through our own user interfaces is limited by our capacity, budget, knowledge of users' needs and imagination.

By building open APIs we allow third parties to use their capacity, budget, knowledge and imagination to build healthcare software that might meet some users' needs better.

Moreover, third parties can combine our services' capabilities with their own capabilities to create novel and innovative solutions to health and social care problems.

Front-end application
Front-end appli...
Back-end application
Back-end application
User Interface (UI)
User Interf...
End user
End user
Business Logic
Business Lo...
Text is not SVG - cannot display The 'API first' approach to building digital services


This policy is in line with our policies:

2: Good quality documentation

All our APIs must be:

  • listed in the NHS API catalogue 

  • documented to a good standard 

  • documented using OAS, if RESTful 

Poor quality documentation has historically been a big pain point for API consumers. Documentation has been hard to find, and hard to understand once found.

Good API documentation aligns with our API principle to make learning easier and should include:

  • a plain English overview of what the API does

  • who can use the API, and what for - including mentioning it as appropriate in our building healthcare software guides

  • a list of related APIs

  • the status and roadmap 

  • the service level

  • the technology used

  • the network access options - internet and/or HSCN

  • the security and authorisation approach

  • test environment details

  • the onboarding process

  • full technical details of the API's endpoints or interactions, including request and response examples and schemas

Documenting RESTful APIs in OAS format means our API specifications are consistent. It also allows API consumers to generate code and test harnesses more easily, which helps make design and build easier.

For more details on writing good documentation, see Documenting your API in our API producer zone (account required).

3: Internet-facing

All our APIs must be internet-facing.

Historically, our APIs have only been available on our Health and Social Care Network (HSCN). When it was first launched - as its predecessor N3 - this was a good way to ensure healthcare systems could talk to one another securely. But HSCN presents a barrier and a pain point to people building healthcare software - HSCN connections cost money and take time to install.

Network and security technology have moved on, and it's now possible to provide secure integration for healthcare digital services on the open internet.

Internet-facing APIs help to make design and build easier.

For more details, see Network access for APIs.


4: Conform to technical standards

All our APIs must conform to our API technical standards.

Conforming to open standards, that are well known by software developers, and well supported by tool and library providers, makes it easier to write code that consumes our APIs. This all helps to make design and build easier.

The following table lists our API technical standards:

Feature Comments
4.1: API is synchronous, if appropriate The Integration Patterns Book recommends using synchronous APIs in preference to other integration types.
4.2: API is RESTful, if appropriate The Integration Patterns Book recommends using REST for synchronous APIs.
4.3: API uses FHIR, if appropriate Our new APIs must use FHIR where data conveyed can reasonably be expressed using FHIR.
4.4: API uses FHIR R4, if appropriate Our new APIs that use FHIR must use FHIR R4. Existing APIs are encouraged to migrate.
4.5: API uses FHIR UK Core, if appropriate Our new APIs that use FHIR must use FHIR UK Core. Existing APIs are encouraged to migrate.
4.6: API uses valid FHIR API uses FHIR validation tools to ensure payloads are valid FHIR, ideally in production.
4.7: API uses an appropriate, modern, security pattern We prefer OAuth to TLS-MA for security.

5: API platform

All our APIs must use our API platform or provide equivalent functionality.

Historically, our APIs have been built and deployed to a variety of hosting platforms, with a variety of different methods for authorisation, access to environments, onboarding and so on - giving API consumers an inconsistent integration experience.

If we publish all our APIs through our API platform, this gives API consumers a consistent integration experience.

It also provides a quicker and easier way for our teams to build APIs.

There may be exceptions to this rule. For example, our authentication APIs - NHS CIS2 and NHS login - are integrated with the API platform but are not proxied through it in the standard way.

6: Self-service testing

All our APIs must provide self-service integration test environments.

Historically, getting access to integration test environments has been a big pain point for API consumers. We have made it difficult for API consumers to find out how to access test environments, and made it a manual process to get access and to get test data set up, depending on key people on our side to be available to grant access.

If we can provide self-service access to test environments, API consumers can get on with testing more quickly and easily, and it's also less burden on us.

As part of this, we need to make sure there is appropriate test data available in our environments, and where appropriate there are self-service tools for setting up test data.

This policy aligns with our API principle to make testing easier.

7: Digital onboarding

All our APIs must use digital onboarding for API consumer onboarding.

Historically, as an API consumer, onboarding to use our APIs in the production environment has been mentioned as pretty much the biggest pain point of all.

We have used onboarding processes that are overly manual, and optimised for our own interests, not those of the API consumers.

If we use digital onboarding for our APIs, and work to reduce the number of governance points to the bare minimum - whilst also respecting security, information governance and clinical safety - we can make it quicker and easier for API consumers to onboard.

This policy is in line with our API principle to make onboarding easier.

8: Out of beta within 6 months

All our APIs must be out of beta within six months of launch.

Feedback from API consumers is that some of them are reluctant to integrate with an API that's still in beta - because it potentially means breaking changes, issues and costly rework.

Moving APIs out of beta as soon as possible - as long as we have evidence that they are fit for purpose - helps API consumers be confident they can integrate without these concerns.

9: Empowered product owner

All our APIs must have a named product owner, product manager or service owner who is empowered to do that role effectively.

APIs that have no product owner do not get properly looked after, and quality suffers as a consequence.

All digital services need a product owner, and APIs are no different.

The product owner must:

  • be empowered to make decisions about what the API does
  • have the resources and budget to build and maintain the API
  • define what success looks like for the API, for example by setting adoption targets
  • think about how to make sure the API gets used, for example via comms and engagement
  • pro-actively gather feedback from API consumers and end users and use it to fix or improve the API
  • make sure the API conforms to all the other API policies on this page


To bring our APIs in line with the above policies, we are:

  • reviewing our existing digital services to identify opportunities to build more APIs
  • building new APIs on our API platform, which supports all the key features listed above
  • sunsetting older APIs where they have been superseded or are obsolete
  • reviewing existing APIs against a more detailed 'what good looks like' checklist to identify opportunities to improve
  • converting existing API specifications to OAS format where possible
  • identifying APIs which could easily be made internet-facing
  • adding more APIs to digital onboarding
  • working with API producer teams to move their APIs out of beta where appropriate
  • working with senior managers to identify where APIs do not have an empowered product owner

Last edited: 9 November 2023 11:14 am