Skip to main content

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:

A synchronous API, showing both request and response

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:

A synchronous API, with a single arrow showing both request and response


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:

Asynchronous API showing the response is not immediate.

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:

An asynchronous API response

Asynchronous APIs are generally used when:

  • the sending system does not need a response
  • the request might take a long time to process

Intermediaries

Often, systems send messages via an intermediary known as a 'proxy' (for synchronous APIs) or a 'message broker' (for asynchronous APIs).

Sending via an intermediary proxy. for synchronous APIs.

Some message brokers deliver the message on to the recipient, like a postal van:

Sending via an intermediary broker for asynchronous APIs.

Other message brokers require the recipient to check for messages, like a post office box:

Recipient checks for new messages with some message brokers.


Publish-subscribe events

Sometimes a system wants to broadcast the fact that something has happened to all interested parties, for example a patient death.

We call this a publish-subscribe events model, and it works very much like Twitter:

  • receiving systems subscribe to event types, for example patient death

  • publishing systems publish events of that type to the event management API

  • the event management API forwards the event on to all interested parties

Our national service for managing events is NEMS (National Events Management Service). It uses another of our services to deliver events to interested parties - MESH (Message Exchange for Social care and Health), as follows:

Publish and subscribe to event model


APIs in context

Systems usually talk to one another due to user actions. For example:

A GP using a GP system to get patient data from the Personal Demographics Service

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 'central systems' such as the Personal Demographics Service or the Summary Care Record. We often refer to these as 'central API services'.

Sometimes, local systems need to talk to other local systems. They might talk directly to one another via 'API standards', for example, Clinical Decision Support standards:

Systems talking to each other via API standards.

More commonly, they talk via an intermediary such as a proxy or national message broker system. We sometimes refer to this as an 'intermediary API service'. For example, the GP2GP HL7 V3 API:

A GP administrator transferring a patient's healthcare record from one GP system to another


API specifications

For systems to talk to one another, they need to agree what to say and how to say it. 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 reads the API specification and builds their system accordingly.

An API specification is published by the developer of the responding system and read by the developer of the requesting system

We publish a catalogue of API specifications for all our APIs.


API standards

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:

Some of these API standards are defined by us (NHS Digital) and you can find them listed in our API catalogue.


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:

  • REST
  • SOAP
  • FHIR
  • HL7 Version 3
  • and more

For more details, see API technologies at NHS Digital.


API security

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.

Last edited: 15 June 2021 4:51 pm