API delivery process

Our API delivery process includes all the steps needed to build and run a good healthcare API.

Our process is based on the GOV.UK agile delivery process, but with an API focus.

Before you start, you should:

• get an overview of healthcare technology, integration and APIs by reading our introduction to healthcare technology and, in particular, the section on integration and APIs
• learn about existing APIs for specific functional areas or care settings by reading our non-technical guides to building healthcare software
• have a more detailed look at some existing APIs in our API and integration catalogue and, in particular, our ‘exemplar’ API – the Personal Demographics Service FHIR API
• read about our vision, mission, principles and roadmap
• read about our API policies and best practice
• learn about our API platform and the benefits of using it

We can help you build your API by:

• allowing you to use our API platform
• giving you help and support along the way

To engage formally with us, follow the inception phase of our API delivery process.

This includes arranging a ‘kick off meeting’ – an opportunity for us to meet, discuss your API, and point you in the right direction.

To access the guidance, see Getting started.

APIs are great way for IT systems to share information, and we strongly encourage their use as per our API first policy.

However, they are not suitable for every situation, so it’s important to make sure an API is right for you.

You should do this as part of your discovery work before you start building anything. You’ll need to:

• understand the problem you’re trying to solve
• find out who your end users are and understand their needs
• consider architectural options, including whether or not to build an API
• select the preferred design
• estimate the build cost

We help and support you with your architecture, and make sure it conforms to the relevant technical standards.

To complete these tasks, you need people with the following skills:

• user research
• business analysis / service design
• technical architecture

For more details, see the discovery phase of our API delivery process. To access the guidance, see Getting started.

You need funding to:

• build your API
• run and maintain it once it’s live

If you are operating within NHS England, you get funding through the normal transformation, maintain and run budgeting processes.

If you are outside NHS England, the following links might help:

• NHS Accelerated Access Collaborative
• NHS Innovation Service
• NHS Innovation Lab

You need a team to:

• build your API
• run and maintain it once it’s live

There might be an existing team you can use, or you might need to build one from scratch.

An API is a bit like the front door of a house. The door provides a way in and out of the house, but it is not the house itself. Likewise, an API provides a way into a back-end application, to send and receive information, but it is not the application itself.

Having a different team build the API leads to all sorts of problems to do with ownership and understanding of the end-to-end system. This is the feature teams versus component teams debate as applied to APIs.

It follows that the team should be multidisciplinary and have all the skills necessary to build an API.

Moreover, that team should have an empowered product owner who is responsible for the application and all of its interfaces, whether they be user interfaces or APIs.

If you use our API platform, we help you build your API, but you own it and have autonomy over it.

Delivery teams sometimes forget that IT systems need to be run once they are live.

APIs are no different – they need to be run. Someone needs to keep the lights on. In some cases, someone needs to be available 24x7 to deal with any issues or outages.

Moreover, someone needs to help API consumers to integrate with the API. They need help and support during development, and someone needs to check they have done everything properly before they go live. We call this ‘onboarding’.

This approach is known as ‘you build it, you run it’ and aligns with the DevOps movement and the concept of continuous improvement.

Whether you use an existing team or build a new one, you should make sure they have the right skills:

• product ownership – an empowered product owner who has the mandate and resources to build and run the API, including managing priorities and acting on user feedback
• business analysis / service design – to ensure you’re building the right thing
• user research – to engage with API consumers
• API design – including FHIR API design if appropriate
• software engineering – to build the API code and test environments
• technical authoring – because good quality API documentation really matters
• technical architecture – for ongoing architectural support
• delivery management – ideally someone familiar with agile software delivery
• onboarding – managing the process for onboarding API consumers

Note that these are skills, not roles. Some team members might be able to cover multiple skills. For example, some business analysts are really good at technical authoring, and some software engineers are really good at API design.

Also, we are available to support your team if they need help. For example, we have architects who can help with API design and technical authors who can help with API documentation.

Intermediary APIs are different. They do not have a single back-end application – they connect to multiple back-ends – so there is no single back-end team.

But they still need to be built and they still need to be run. So there needs to be an owning team that exists beyond the build phase.

Because intermediary APIs are fairly simple, intermediary API teams sometimes struggle to justify having dedicated software engineers to build and run them.

If you use our API platform to build an intermediary API, we might be able to do your engineering work. You still need to own the API, but we can build and run the technology.

An alpha is a prototype of your API for testing and feedback.

In the alpha phase, you:

• design your API
• publish your API specification
• build your API proxy
• build transformation logic, if required
• provide test environments
• work with early adopters to get feedback and iterate the design

We help with your detailed API design and make sure it is consistent with our standards for REST and FHIR, and with other APIs.

You:

• create an Open API specification (OAS) file for your API
• publish it in our API and integration catalogue

Your API specification is then available for early adopters to review and express an interest.

You:

• create a GitHub repo for your API with a single click, based on our repo template
• customise your API proxy as appropriate, using our documentation and with our support

During alpha, your API proxy is only deployed to test environments, not production, so you do not need to worry too much about setting up things like rate limiting, logging, monitoring and alerting.

If your API proxy needs to connect to an existing back-end API that uses a legacy format, such as HL7 V3, you can build a transformation layer and deploy it to our hosted container environment.

Our hosted containers are hosted in the cloud on AWS.

You need to consider providing:

• a sandbox environment
• a formal integration test environment

A sandbox API is a ‘stub’ that returns ‘canned’ responses to requests, and is used for early developer testing. It is:

• open access – no security wrap
• hosted in the cloud on AWS

A formal integration test environment is intended to be as close as possible to production, so typically includes:

• an API proxy with security wrap
• a back-end application deployed in a test environment
• ready-to-use test data

To find out if your API design is fit for purpose, engage with early adopters and get their feedback. This might be based on them reading the API specification or using the test environments.

Use their feedback to iterate your API design.

In the beta phase, you:

• get your API ready for production
• put it live
• prepare for onboarding
• onboard early adopters
• work with them to get further feedback and iterate the API

Before your API can be deployed to production, you need to set up things like:

• rate limiting
• logging
• monitoring and alerting
• live support processes

You might also need to review it with various stakeholder groups such as:

• clinical safety
• security
• information governance
• legal

Deploy your API to production and smoke test it to make sure it’s working.

Work with us to define the onboarding process for your API. This is the process API consumers need to follow before they can connect to the API in the production environment.

It includes things like:

• completing security checks
• considering information governance
• doing a clinical risk assessment
• signing a legal agreement

Our digital onboarding tool is the easiest way to manage API consumer onboarding. It’s mandated for all new NHS England APIs and strongly recommended for other APIs.

We help you get set up for digital onboarding and train your onboarding lead.

Trial your API and onboarding process with early adopters.

This is where you tend to discover issues with live data quality or assumptions about how the API works.

Use their feedback to iterate the API and the onboarding process.

Once you onboarded enough early adopters, and have enough confidence that your API is fit for purpose, you can exit beta.

From the point that you onboard your first early adopters to your beta API, you are running a live API, including:

• technical and non-technical support for API consumers during integration
• onboarding API consumers
• live service support – to the appropriate service level
• continuing to iterate and enhance the live service based on user feedback
• keeping up to date with software patches

Once you exit beta, you do not need as big a team to run an API, but you do still need a team. Importantly, you should continue to have an empowered product owner throughout the life of your API.

Your API is no use if nobody uses it. So you need to think about how you encourage adoption.

We have some experience in this and are happy to provide advice.

Eventually, your API might reach the end of its useful life. Maybe it has been superseded by a new API or a new version of the same API. Maybe its use case is no longer relevant.

However, you cannot just switch it off if it’s still being used. Instead, you mark it as deprecated.

A deprecated API is still available and supported, but is planned for retirement.

Part of the deprecation process is to contact existing users to discuss a suitable date for retirement.

When you have no more API consumers using your API, you can retire it. A retired API is no longer available for use.

For detailed guidance on building healthcare APIs, see our API producer zone. You'll need an NHS England Confluence account to access this. In the meantime, you can download:

• our API Producer Overview slide deck
• a snapshot of the API producer zone as a PDF file - taken on 29 April 2022 and with some sensitive information removed