We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
Introduction to APIs
A gentle introduction to APIs and how they work.
On this page we explain what APIs are and how they work.
If you already understand terms like REST and JSON, you might want to skip this and go directly to our API catalogue to find out what APIs are available.
What is an API?
API stands for Application Programming Interface. Simply put, an API allows computer systems to talk to one another. Here’s an example:
In the above diagram:
- System A requests patient data (for a specific patient) from System B (the “request”)
- System B finds the data for that patient and returns it to System A (the “response”)
We say that System B “presents” or “exposes” an API, and that System A “calls” or “makes a request to” that API.
Because the response is usually implicit, we sometimes draw the diagram with a single arrow, like this:
Synchronous and asynchronous APIs
With a synchronous API, the response is immediate, as in the example above. We sometimes call this a “real time” response.
With an asynchronous API, the response is not immediate, other than to acknowledge receipt. For example:
This is sometimes called a messaging API or a “fire and forget” API. It’s similar to paper mail or e-mail with recorded delivery. The sender knows the message has been received, but not that it has been processed.
The receiving system might send a message back to the original sender some time later. For example:
Often, systems send messages via an intermediary known as a “message broker”. Some message brokers deliver the message on to the recipient, like a postman:
Other message brokers require the recipient to check for messages, like a post office box:
Asynchronous APIs are generally used when:
- the sending system doesn’t need a response
- the request might take a long time to process
APIs in context
Systems usually talk to one another due to user actions. For example:
In most cases the users are using “local systems” such as GP systems, hospital systems or ambulance service systems, and the local systems talk to “national systems” such as the Personal Demographics Service or the Spine Clinical Record.
Sometimes, local systems need to talk to other local systems. They might talk directly to one another, for example:
More commonly, they talk via a national message broker system. For example:
For systems to talk to one another, they need to agree what to say. To do this, the developer of the responding system publishes an API specification that explains exactly how to call the API.
The developer of the requesting system read the API specification and builds their system accordingly.
We publish a catalogue of API specifications for all our APIs.
If all systems talk the same language, it makes it easier for software developers to get them to talk to one another.
Over the years, various international and national bodies have published standards for APIs. Some of them apply to APIs in general, some of them apply to healthcare globally and some of the apply to healthcare in the UK and England. Some of the UK and England ones are published by us (NHS Digital).
API technologies at NHS Digital
NHS Digital has been developing APIs for quite some time. We always aim to adopt the latest standards for new APIs. But it’s costly to rebuild APIs when technology changes. As a result, our APIs use a variety of technologies, including:
- HL7 Version 3
- and more
For more details, see API technologies at NHS Digital.
Most of our APIs give access to personal or sensitive data. We have a responsibility to make sure it is only made available to the right people.
We do this in a variety of different ways depending on the type of API. For more details see security and authorisation.