Our API technologies

We've 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, some more modern than others.

Some of our APIs are basic RESTful APIs. 

RESTful APIs:

• are synchronous - they give an immediate response
• are accessed using HTTP - the same way a web browser accesses web pages
• give access to data as 'resources' - like web pages, for example https://api.service.nhs.uk/personal-demographics/Patient/9000000009 accesses the demographic data for the patient whose NHS number is 9000000009
• use HTTP verbs such as GET and POST to get and update those resources
• use HTTP status codes for errors, for example HTTP status 404 means 'resource not found'
• in some cases, use HAL links to link to other resources
• in most cases, use the JSON format for requests and responses (although some use XML)

In some cases, this means they are "level 0 REST" as defined in the Richardson Maturity Model - which do not meet all these criteria.

Where appropriate, our APIs follow the HL7 FHIR standard (pronounced 'fire').

FHIR (Fast Healthcare Interoperability Resources) is a global standard for health care data exchange. It is the successor to the HL7 V3 standard.

FHIR:

• defines specific resources for the health care domain, such as Patient and Observation, and also defines common data items for those resources
• can be adapted for local requirements using profiles, extensions, terminologies and more
• defines rules for how to access resources via RESTful APIs
• can also be used for messaging and document solutions

There are multiple versions of FHIR:

• FHIR DSTU2 is a draft standard for trial use - we don't have many APIs using this
• FHIR STU3 is a standard for trial use - we have some APIs using this
• FHIR R4 is the latest normative release - we use this for all our new APIs

FHIR has been adapted for use in England as follows:

• CareConnect is a set of England-centric FHIR profiles built on FHIR STU3
• FHIR UK Core is a set of UK-centric FHIR profiles built on FHIR R4 that applies to all of the NHS
• the NHS England FHIR Implementation Guide covers additional profiles for our extensions to these FHIR UK Core profiles

Some of our FHIR APIs are RESTful.

You don’t need to know much about FHIR to use them - RESTful FHIR APIs are just RESTful APIs that follow specific rules. In particular:

• resource names are capitalised and singular, for example /Patient not /patients
• array names are singular, for example line not lines for address lines
• data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an extension object

Some of our FHIR APIs are messaging APIs that follow the FHIR messaging standard.

In general, our FHIR messaging APIs use MESH as the message transport layer.

We have defined policies for the use of FHIR in the NHS in England.

For details, see FHIR policy.

There is an ever-increasing list of open source FHIR libraries appearing on the web, written for a wide variety of languages such as Java, C#.NET, JavaScript and PHP. These exist to make integration easier with FHIR APIs.

You might find the following open source tools useful.

FHIR libraries:

• C#.NET Firely FHIR API 
• Java HAPI FHIR 
• JavaScript Smart on FHIR 
• Python Smart on FHIR 

FHIR reference servers: 

• C#.NET Spark FHIR Server 
• Java HAPI FHIR
• SMART on FHIR

You can explore other options with the Health Level Seven (HL7®) international standards body which maintains an extensive list of open source FHIR implementations. 

We welcome your feedback on tools you have found useful.

Some of our APIs are basic SOAP (Simple Object Access Protocol) APIs.

This includes, for example, the Directory of Services - SOAP API.

Some of our older APIs use the HL7 Clinical Document Architecture (CDA) as a payload standard to exchange clinical information between systems.

CDA uses XML, the HL7 V3 standard and coded 'vocabularies' of clinical terms to exchange documents that are both machine and human-readable. This allows electronic processing for decision support while remaining easy to read by healthcare workers.

Content can include text, images, sounds, other multimedia and usually includes a signature.

Typical uses for a CDA document include healthcare records, discharge summaries, referrals, clinical summary reports, lab reports and so on.

The typical structure of a CDA document includes a:

• header with details of the  patient, author, provider, document type and so on
• body containing a human readable part, any signature and any MIME encoded content - followed by an encoded part containing the key machine-readable details as defined by a CDA profile for that type of document.

CDA V1 was produced in 2000 and CDA V2 in 2005. CDA documents are no longer widely used.

Some of our older APIs conform to the HL7 Version 3 standard.

HL7 V3 is a global standard for health care data exchange. It is the predecessor to the FHIR standard.

It includes:

• synchronous APIs, using SOAP and XML
• asynchronous APIs, using ebXML

Be aware that using our HL7 V3 APIs can be hard work because:

• the documentation is quite hard to navigate
• the message structure is complex
• for asynchronous APIs you need to build a Message Handling System to receive inbound messages

If there is a suitable RESTful API available, we recommend you use that instead.

Learn how to integrate with our HL7 V3 APIs by reading:

• part 2 of the Spine External Interface Specification, which explains the general syntax
• part 3 of the Spine External Interface Specification, which explains which interactions are synchronous and which are asynchronous
• the Spine Message Implementation Manual, which explains the message payload structure for each interaction

Message Handling Service adaptor

To remove the complexity of building your own Message Handling System, we offer a pre-assured, client side Message Handling Service adaptor that you can integrate into your own infrastructure.  

Some of our synchronous APIs are available via the Spine Security Proxy (SSP). We use SSP where the responding system is another local system. Requests and responses go via SSP instead because this makes it easier for responding systems - they only have to deal with requests from a single place.

To make sure all systems can talk to one another, we write the API specifications for SSP APIs, even though we don’t own the responding systems.

SSP APIs are generally FHIR APIs, the only difference being that SSP sits in the middle, routing traffic and making security easier.

Some of our asynchronous APIs use MESH (Message Exchange for Social care and Health). MESH is our messaging hub that allows systems to send and receive asynchronous messages. MESH replaced an older system called DTS.

With MESH, sending systems send messages to a messaging hub and the messages are placed on the recipient’s “queue”. Receiving systems must constantly check the messaging hub for incoming messages on their queue. This is known as a “pull” or “polling” mechanism.

MESH is built as a RESTful API with endpoints for sending messages and for polling for received messages.

The message payload format depends on the specific API. For example, pathology messages use HL7 v2 EDIFACT, whereas transfer of care messages use FHIR.

The national service for publish-subscribe events is the National Events Management Service (NEMS).

With NEMS:

• receiving systems use the NEMS API to subscribe to event types
• publishing systems use the NEMS API to publish events of that type
• NEMS sends relevant events to subscribed systems via MESH

The Spine Directory Service API uses Lightweight Directory Access Protocol (LDAP).

LDAP is a simple way to access information held in a hierarchical directory structure over an Internet Protocol (IP) network such as HSCN or the internet. It is an open standard with multiple versions. See individual API documentation for details of which version is used.

Some of our oldest asynchronous messaging APIs use EDIFACT.

Electronic Data Interchange For Administration, Commerce and Transport (EDIFACT) is an international EDI standard for the exchange of messages that was adopted by organisations wishing to trade globally. The United Nations ratified a standard set of syntax rules so it's sometimes referred to as UN/EDIFACT. 

Some of our APIs use OAuth 2.0 for authorisation. OAuth 2.0 is an open standard for API authorisation and is generally considered to be the best was to secure modern RESTful APIs.

There are a variety of 'flavours' of OAuth 2.0, and we use three of them:

• 'authorisation code flow' - where the end user authenticates directly with one of our identity providers (NHS CIS2 or NHS login) as part of the process of obtaining an access token
• 'token exchange' - where the end user authenticates with an identity provider separately using Open ID Connect (OIDC) and then exchanges their ID token with an API access token
• 'JSON web tokens' - where the calling application authorises securely without end user involvement

For more details on how we use OAuth 2.0, see the various security patterns on our security and authorisation page.

Some of our APIs use OpenAPI Specification (OAS) - previously known as 'Swagger' - to describe the API's interface.

OAS is a global standard for describing RESTful APIs in a human and machine readable format.

The OAS file for each API contains general documentation as well as specific details of endpoints, including request and response headers and bodies.

We use the OAS file under the covers to generate the API specifications in our API catalogue.

You can also download the OAS file for an API -  go to the API specification and look for the "Get this specification in OAS format" button.

You can use a tool such as Swagger Codegen to generate stubs, test harnesses and SDKs in your favourite programming language.

Our OAS files use OAS version 3.

To see a list of APIs that use OAS, see our API catalogue, filtered to show APIs that use OAS.