Skip to main content
Blog

What does good look like for APIs?

Matthew Firth describes our best practice policies around APIs – and how the most important one is not about the technical aspects of the work.

For the past 3 years, we have been on a mission to make integration easier within the NHS for people building healthcare technology.

The author Matty Firth

To that end, we have:

  • built an API platform, which has become the national API platform for NHS England
  • built an exemplar API, the Personal Demographics Service FHIR API
  • built a number of other APIs on the platform
  • sunsetted older APIs in line with our policy
  • created an API and integration catalogue which lists all our APIs, old as well as new
  • developed a digital onboarding service to enable easier access to APIs

We have made lots of progress, but there is more to do.


Quality matters

Quality is an ongoing challenge. We have had a lot of great feedback from API consumers, so we know what a good API looks like, and have a clear set of API principles.

But each API is built and run by a different team, and making sure everybody plays by the same rules is never easy. Making the case to improve existing APIs is especially tough. Change must be funded, and funding requires a business case.

To help API teams build that case, we’ve published a set of API policies and best practice guidelines to ensure our APIs provide a consistent user experience and give API consumers the confidence that they are built to a high quality. All new and existing NHS England APIs must comply with these policies.

The policies might not be what you would expect. You might think they would focus solely on technical aspects of APIs, such as REST, OAuth 2.0 and FHIR. But conforming to technical standards is only one of the 9 policies.

Here's a full list:
  • API first
  • good quality documentation
  • internet-facing
  • conform to technical standards
  • API platform
  • self-service testing
  • digital onboarding
  • out of beta within 6 months
  • empowered product owner

These policies build upon and extend central government API technical and data standards.

The last policy, having an empowered product owner, is really important to us. Having a person who cares about an API, and who has the budget and resources to improve it, is an essential foundation for all the other policies.


How are we doing?

Defining these policies also allows us to measure progress against them for our existing APIs, some of which pre-date the API platform. For example:

  • 67% of our APIs are internet-facing
  • 31% of our APIs have self-service testing
  • 22% of our APIs use digital onboarding
  • 45% of our APIs have an empowered product owner

As you can see, we are doing better on some measures than on others.


Driving change

It is our intention that by publishing these figures, and working with our API delivery teams and those who build healthcare software, we will continue to drive change. And that by working with our empowered product owners, we will improve the experience of those software development organisations wanting to integrate with us.

The above statistics might be somewhat reductionist, but hopefully we can use them to drive positive change from within. We want to avoid producing complex dashboards that are time-consuming to maintain and ultimately don’t help us measure our progress.    

Feedback from API consumers is also essential, so if there is anything specific you would like to see us do, tell us about it via our interactive product backlog.



Related subjects

Tony Heap, Lead Product Owner for API management at NHS Digital, explains how our new API platform can create a more competitive marketplace for healthcare systems.
Thasmim Ali, Product Owner of our API Developer Community, talks about how we’ve improved support for teams integrating with our products and services – and outlines our next steps.
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.

Author

Last edited: 14 December 2023 3:40 pm