This section intends to give developers detailed requirements and guidance to interact with the NRL for the creation, management and retrieval of pointers, outlines the information available and lists some pre-requisites for using the NRL service.
In the requirement pages, keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, ‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’, ‘RECOMMENDED’, ‘MAY’ and ‘OPTIONAL’ are to be interpreted as described in RFC 2119, in order to create an NRL compliant system.
NRL Interactions
The NRL supports the following interactions as detailed in the Architectural Overview page:
| 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 an NRL pointer. |
| 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. |
Explore NRL Interactions
You can explore and test the NRL interactions using Swagger (NRL API Reference Implementation).
Generic Requirements
Endpoint Registration
For an organisation to be able to use the NRL:
- the system they are using MUST have been accredited through the assurance process.
- the organisation MUST have been given an endpoint certificate and associated ASID for the environment (INT, DEP, LIVE) they wish to connect to.
- the organisation’s endpoint MUST have been configured with the required interaction ids and service permissions.
NHS Number
NHS Numbers used within any interaction with the NRL, MUST be traced and verified prior to submission.
Verification of an NHS Number can be achieved using:
- a fully PDS Spine-compliant system (HL7v3).
- a Spine Mini Services Provider (HL7v3).
- 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.
JSON Web Token
A JSON Web Token (JWT) is required for all interaction with the NRL and SSP. All requirements for JWT population can be found on the JSON Web Token Guidance page.
Interaction Content Types
The NRL supports the following MIME types for NRL interactions:
XML
application/fhir+xmlapplication/xml+fhirapplication/xml
JSON
application/fhir+jsonapplication/json+fhirapplication/jsontext/json
Response Format
The NRL supports the following methods to allow the client to specify the response format by its MIME type:
- the HTTP
Acceptheader. - the optional
_formatparameter.
If both are present in the request, the _format parameter overrides the Accept header value in the request. If neither the Accept header nor the _format parameter are supplied by the client system, the NRL server will return data in the default format of application/fhir+xml.
Security
Generic requirements for security, authentication and authorisation are included in the specification on the Security Guidance page.
Retrieval
Requirements on information retrieval formats and retrieval mechanisms are outline in the Information Retrieval section of this specification.
