Skip to main content

What we have learned about retiring APIs

Business analyst Matthew Firth gives an update on what NHS Digital has been doing to progress the API ‘sunsetting’ strategy to retire some of our APIs over the last year.

Last year we published our blog What happens when we ‘sunset’ our APIs?’ in which Munish Jokhani explained how we actively deprecate (where we advise of our intention to retire the API while retaining all existing service levels) and retire our APIs, and the effect this had on developers. By working with our suppliers and engaging them early in the process, we found that we were able to agree and align the retirement dates so that we met our suppliers’ requirements. 

Abstract image with graphics showing computer screens and shapes

The last 12 months

The total number of APIs in our API Catalogue fell from 67 to 61 in 2022, despite APIs being added. The main reason for this difference is due to us actively deprecating and retiring APIs which are no longer part of NHS Digital’s API platform strategy.  

What is sunsetting?

Over time, older APIs become obsolete – either because they are no longer being used or because they have been superseded by something newer and better.  

When we gradually deprecate and retire an API it is called sunsetting. During this process, the API is available for use with the same service levels, but we are unlikely to make updates and won’t permit new integrations unless they are already underway. We consult with API users on our plans for retirement and the expected date that we will retire the API. 

The key driver for sunsetting APIs is to provide clarity to both suppliers and our own API producer teams.  We acknowledge that knowing which API to use is confusing when we have multiple APIs that seem to do the same job. Investing effort into integrating with our APIs can incur a significant cost, so knowing which API to invest in is valuable for our suppliers. This responds to feedback that our suppliers have shared with us about how we can make their integration journey easier. 

When we have built an updated version of the API, built an API that provides equivalent capabilities, or if the existing API is no longer fit for purpose, has limited usage or is a security risk we will look to deprecate and then eventually retire it. 

Deprecating the Personal Demographics Service SMSP API in October 2021 allowed us to create an exemplar process which we were able to test and prove concepts around supplier engagement and managing their expectations. 

In the last year alone, we have retired 11 APIs and have deprecated a further 8 and there are plans to start the sunsetting journey for more as we move into 2023. 

In the summer of 2022, we reached a major milestone; the deprecation of the Gazetteer SOAP API.  We agreed with suppliers on a retirement date of 31 October 2023 and recommended that both existing users and new consumers use the Ordnance Survey OS Places API instead. This was a significant step for us, as it allowed us to open our API Catalogue to external APIs. 

Key findings

One of the key findings we identified was that when we consulted with the suppliers and asked them how long they would need to migrate away from the API, the more receptive they were with their feedback. Of course, it is not possible to say yes to every retirement date request, however, where there is common ground, or where there is an obvious average across suggested retirement dates, we found that it was possible to meet the requirements of most of our suppliers.

A big win has been the implementation of a proven process which other teams can pick up and use easily.

A challenge for us is working out who is using our open-access APIs, as we are unable to identify and contact suppliers to discuss the proposed changes and potential sunsetting process with them. In future, we’ll be making our APIs application-restricted, so that we know who’s using them.  

A big win for the team has been the implementation of a proven process which other teams across NHS Digital can pick up and use easily. We have developed an approach which uses consistent language with an easy-to-follow process flow and well-documented checklist.  

We have now found that teams are contacting us to ask us what we do with older versions of APIs and if we have a process in place for sunsetting an API. The feedback we receive when we present the process and checklist is consistently positive as we look to the teams to take ownership of their own sunsetting journeys with support from the API Management team. 

What lies ahead

We have tackled what we would describe as the low hanging fruit – the APIs which were never implemented, those with low traffic and those which have been succeeded by newer, improved versions. Some of these have already been retired and others are in their sunsetting phase, having been deprecated in 2022. We won't progress with the retirement of those APIs this year due to the agreements in place with existing suppliers on retirement dates, but we will see an increase in retirement activity in 2024. 

Our focus will turn to educating API teams on the benefits of sunsetting APIs.

We anticipate the next 6 months or so to be more of a waiting game – the sunsetting process for an API will not start again until the replacement API is in place. Our API deprecation and retirement policy outlines the requirements to allow us to make progress. We are awaiting the implementation of replacement APIs before we can proceed with sunsetting the older ones.  

Our focus will turn to educating API teams on the benefits of sunsetting APIs using our proven process. While API Management will be on hand to support teams on their own sunsetting journeys and share our experiences of best practice, the expectation is that each team will own their individual process and adapt it in accordance with their own use case. We will make our templates and guidance public so teams can access the resources easily as they prepare to begin their sunsetting journey. 

API teams will need to develop all the features for new APIs which are necessary to allow us to deprecate the older APIs. We will work with the API teams to ensure that the requirements are understood and that the API solution which is delivered includes both the functionality and features required to allow the deprecation and retirement of the older API.   

Get involved

We are committed to co-creation and collaboration and that is the reason we are consulting on retirement timescales and on our broader vision around API Management with our developers and the wider tech industry. 

For details on other APIs that are currently in the sunsetting process, see our interactive product backlog. You can also suggest, comment, or vote on APIs and platform features using the backlog.  

If you have any feedback, please contact us

Related subjects

Business analyst Matthew Firth talks about the expansion of NHS Digital’s application programming interface (API) and integration catalogue which, for the first time, will now include external 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.
Sam Perera, API Delivery Manager at NHS Digital, explains how we are making it easier to use our APIs.


Last edited: 12 January 2023 12:08 pm