Skip to main content

What happens when we ‘sunset’ our APIs?

Dr Munish Jokhani, Assurance Lead for API Management at NHS Digital explains how we retire our APIs and how developers can get involved in the process.

We have around 85 items in our API and integration catalogue at NHS Digital, and this collection of APIs and API standards is playing a really important role in opening up national systems and driving innovation.

Dr Munish Jokhani working at his desk at home.

Our catalogue is constantly developing, and, like all major API providers, that creates an issue for us and our users.

We can’t run APIs indefinitely – the cost is significant – and, with new APIs added to the catalogue, maintaining both old and new versions of APIs with overlapping functionality can cause confusion for people who want to integrate with them.

I want to explain how we manage our API estate in this blog. When new versions of APIs are available, we ‘deprecate’ the old ones – meaning we no longer recommend them for use – before retiring them. We take deprecation and retirement seriously because we appreciate that these processes can cause developers inconvenience. We are also very aware of our obligation to use public funds efficiently.

API lifecycle

Throughout their lives, we tag our APIs with a status: alpha, beta, stable, deprecated and retired. This is based on the GDS agile delivery process.

We use a gradual ‘sunsetting’ process when we deprecate and retire an API. When we deprecate an API this means:

  • 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 integrations that are already underway
  • we will consult API consumers on an appropriate date to retire the API
  • we will let API users know about our plans for retirement – usually by email and also on our website

We have a deprecation and retirement policy that provides more information on the process.

How the process works in practice

Recently, we introduced our new Personal Demographic Service (PDS) API. It’s our exemplar API which supports FHIR (Fast Healthcare Interoperability Resources) version 4 – the latest global standard for healthcare APIs – which is easier to use than previous standards.

This PDS FHIR API is in high demand and has reliably handled countless millions of transactions over the last year. If you booked a coronavirus vaccination online, you have already used the PDS FHIR API as it searches and retrieves patient information from PDS as part of the service’s identity checks. The National Immunisation and Vaccination Service (NIVS) and the new Find your NHS number service​ also use the new PDS FHIR API to either find or verify a citizen's NHS number, which helps to manage and track the vaccination process.​​​​

The success of PDS FHIR API meant we needed to deprecate the PDS - Spine Mini Service Provider (SMSP) API  because the PDS FHIR API provides equivalent functionality. If developers need continued access to PDS, we recommend they migrate their applications to use the new PDS FHIR API.

As per our policy, we have been consulting users around the retirement timescales for the PDS SMSP API in a number of ways. We have also published a migration guide to help API consumers migrating from the PDS SMSP API to PDS FHIR API. 

This deprecation only affects the PDS SMSP API developed by NHS Digital and does not impact on third party PDS SMSP providers or any clients using them. Third party providers use the PDS HL7 V3 API as part of their solution to provide simplified access to the PDS and this API is not being deprecated.

Get involved

The deprecation of the PDS SMSP API is another step to achieve cost effective and sustainable solutions and achieve our API vision. We are committed to co-creation and collaboration and that’s the reason we are consulting on retirement timescales and our broader vision around API Management with our developers and the wider tech industry.

For details on other APIs that are currently being considered for deprecation or retirement, see our interactive product backlog. You can also suggest, comment or vote on APIs and platform features using the backlog.

The sunsetting process is a new process and we want to get it right. If you have any feedback, please contact us.

Interested in working at NHS Digital? Search our latest job opportunities.

Related subjects

Our ‘API-first’ approach is making it easier for developers, suppliers and partners to connect to our platforms and services. Brian Diggle, Technical Architect at NHS Digital, gives a behind-the-scenes look at how this approach works in practice.
Tony Heap, Lead Product Owner for API Management at NHS Digital, explains how our new API Platform will create more opportunities to improve digital health and care services


Last edited: 15 December 2023 11:26 am