1. NRL API Overview
The NRL API supports the following operations as detailed in the Solution Interactions section of this implementation guide:
| Interaction | HTTP Verb | Actor | Description |
|---|---|---|---|
| Read | GET | Consumer | Retrieve a single pointer by Logical ID |
| Search | GET | Consumer | Parameterised search for pointers on the NRL |
| Create | POST | Provider | Create a pointer on NRL |
| Create (Supersede) | POST | Provider | Replace an NRL pointer, changing the status of the replaced pointer to “superseded” |
| Update | PATCH | Provider | Update an NRL pointer to change the status to “entered-in-error” |
| Delete | DELETE | Provider | Delete an NRL pointer |
A system can be assured to perform both Consumer and Provider interactions, provided that all relevant pre-requisites and requirements are met.
2. Pre-Requisites for NRL API
2.1 NRL Server API Conformance
-
MUST support HL7 FHIR STU3 version 3.0.1.
-
MUST implement REST behavior according to the FHIR specification.
-
MUST support XML or JSON formats for all API interactions.
2.2 NRL Client API Conformance
-
MUST support HL7 FHIR STU3 version 3.0.1.
-
MUST support XML or JSON formats for all API interactions.
-
SHOULD support the NRL Service RESTful interactions and search parameters.
2.3 Spine Services
The NRL API is accessed through the NHS Spine. Providers and consumers of the NRL API are required to integrate with the following Spine services as a pre-requisite to calling the NRL API:
| National Service | Description |
|---|---|
| Personal Demographics Service (PDS) | National database of NHS patients containing details such as name, address, date of birth, and NHS Number (known as demographic information). |
Detailed Spine services pre-requisites
To use this API, both Provider and Consumer systems:
- MUST have been accredited and received an endpoint certificate and associated ASID (Accredited System ID) for the client system.
- MUST pass the system/organisation’s information in a JSON web token - see Access Tokens (JWT) for details.
- MUST have previously traced the patient’s NHS Number using PDS or an equivalent service.
In addition, Consumer systems:
- MUST have authenticated the user using NHS Identity or national smartcard authentication and obtained a the user’s UUID and associated RBAC role.
- MUST pass the user’s information in the JSON web token.
2.4 NHS Number
NHS Numbers used with FHIR API profiles MUST be verified. NHS Numbers can be verified using a full PDS Spine-compliant system (HL7v3), a Spine Mini Services Provider (HL7v3), or a Demographics Batch Service (DBS) batch-traced record (CSV).
The option of using a DBS service is for Provider systems only. Consumers performing a search operation MUST use either a full PDS Spine compliant system or a Spine Mini Services Provider.
The NHS NUMBER is 10 numeric digits in length. The tenth digit is a check digit used to confirm its validity. The check digit MUST be validated using the Modulus 11 algorithm.
3. Explore the NRL
You can explore and test the NRL GET, POST, and DELETE commands and responses using Swagger in the NRL API Reference Implementation.
