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.  

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. 

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

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. 

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.   

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.