Skip to content

NRL-1048 remove documentation from api gateway and documentation scripts #971

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eesa456 merged 4 commits into from
Jul 17, 2025
Merged

NRL-1048 remove documentation from api gateway and documentation scripts #971

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
80b7518
NRL-1048 remove documentation from api gateway and documentation scripts
eesa456 Jul 11, 2025
b728a5e
NRL-1048 remove java tool
eesa456 Jul 15, 2025
d1ac2e9
Merge branch 'develop' of github.com:NHSDigital/NRLF into feature/eem…
eesa456 Jul 17, 2025
36811a5
NRL-1048 skip capability test for now
eesa456 Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .tool-versions
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
allure 2.34.0
awscli 2.27.20
java zulu-jre-24.28.83
jq 1.7.1
k6 1.0.0
poetry 1.8.5
Expand Down
227 changes: 0 additions & 227 deletions api/consumer/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,234 +4,7 @@ openapi: 3.0.0
# owned by NHS Digital (https://digital.nhs.uk/)
info:
title: National Record Locator Consumer - FHIR API
description: |
## Overview

The National Record Locator (NRL) enables organisations to share patient data nationwide. Rather than storing the
data itself, it is used to share pointers to the data, held in provider systems. It acts as an index and not a data
repository. Each document pointer is defined using the
[FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html) standard.

![National Record Locator](https://raw.githubusercontent.com/NHSDigital/nrl-consumer-api/master/specification/nrl.png)

Users of the service fall into the categories of:

* producers - capable of creating and managing pointers
* consumers - capable of searching and reading pointers

The service removes the need for organisations to create duplicate copies of information across systems and
organisations, by enabling access to up-to-date information directly from the source.

It can be used to store and publish pointers to patient data held in health systems across England and to look up
where relevant patient data is held.

There is a growing list of health and social care organisations authorised to share records using NRL, and presently
the pointers are classified into the following types:

* [Mental health crisis plan](http://snomed.info/sct/736253002)
* [Royal College of Physicians NEWS2 (National Early Warning Score 2) chart](http://snomed.info/sct/1363501000000100)
* [ReSPECT (Recommended Summary Plan for Emergency Care and Treatment) form](http://snomed.info/sct/1382601000000107)
* [Contingency plan](http://snomed.info/sct/325691000000100)
* [End of life care plan](http://snomed.info/sct/736373009)
* [End of Life Care Coordination Summary](http://snomed.info/sct/861421000000109)
* [Emergency health care plan](http://snomed.info/sct/887701000000100)
* [Lloyd George record folder](http://snomed.info/sct/16521000000101)
* [Advance care plan](http://snomed.info/sct/736366004)
* [Treatment escalation plan](http://snomed.info/sct/735324008)
* [Summary record]("http://snomed.info/sct|824321000000109")
* [Personalised Care and Support Plan]("http://snomed.info/sct|2181441000000107")

You can also retrieve booking and referal pointers however you can not currently do this by directly integrating with
the National Record Locator, you must instead onboard to the [Booking and Referral - FHIR API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir)

### As a Consumer

Consumers can use this API to:

* search for pointers, restricted to a single Patient at a time
* read a specific pointer
* operations are restricted to document types agreed during the [onboarding](#api-description__onboarding) process

### What has changed?

This service is a replacement for the existing
[National Record Locator (NRL)](https://digital.nhs.uk/services/national-record-locator), and has the following
changes:

* upgraded from FHIR STU3 to R4.
* improved performance and scalability.
* improved onboarding experience.
* authenticated using [signed JWT](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) rather than mTLS.
* greater flexibility, by wider support of the [FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html) resource.
* the application only supports json type FHIR, not XML (which is also valid FHIR)

### Data availability, timing and quality

Pointers are available to be consumed almost immediately after they have been produced by the provider.

## Who can use this API

This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go
too far with your development. You must demonstrate you have a valid use case as part of digital onboarding.

You must have the capability to verify NHS numbers by one of the following mechanisms:

* full PDS Spine compliant system
* Spine Mini Service PDS (SMSP)

Connecting parties must have an appointed Clinical Safety Officer and undertake a Clinical Safety Assessment.

You can not use this API to retrieve documents, however you should be prepared to retrieve in PDF or Unstructured
formats.

In order to retrieve a document, consumers must be able to interact with the National Record Locator and the Spine
Secure Proxy (SSP).

You can only use this API if your consuming application is only accessible using a valid NHS Smartcard for all users
or a system that uses an authentication method supported by
[NHS Care NHS Care Identity Service 2 (NHS CIS2)](https://digital.nhs.uk/services/identity-and-access-management/nhs-care-identity-service-2).

You must do this before you can go live (see ‘[Onboarding](#api-description__onboarding)’ below).

## API status and roadmap

This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).

To see our roadmap, or to suggest, comment or vote on features for this API, see our
[interactive product backlog](https://nhs-digital-api-management.featureupvote.com/?tag=national-record-locator-api).

If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support).

## Service level

This API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm),
Monday to Friday, excluding bank holidays.

For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).

## Technology

This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).

It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir)
global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/), except
that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.

It includes some country-specific FHIR extensions, which conform to
[FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically
[fhir.r4.ukcore.stu1 0.5.1](https://simplifier.net/packages/fhir.r4.ukcore.stu1/0.5.1).

You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.

In particular:

* resource names are capitalised and singular, and use US spellings, for example `Organization` not `organisations`
* array names are singular, for example `entry` not `entries` 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

There are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration.

## Network access

This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).

For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).

## Security and authorisation

This API uses the following access modes:

* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)

## Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
* 400 to 499 if it failed because of a client error by your application
* 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.

## Open source

You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:

| Resource | Description | Links |
|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------|
| NRL v3 API | Source code for the core API and sandbox | [GitHub repo](https://github.com/NHSDigital/nrlf) |
| NRL v3 Producer API | Source code for the producer API proxy and specification. | [GitHub repo](https://github.com/NHSDigital/nrl-producer-api) |
| NRL v3 Consumer API | Source code for the consumer API proxy and specification. | [GitHub repo](https://github.com/NHSDigital/nrl-consumer-api) |
| Lambda Pipeline Package | Source code for the lambda pipeline utility | [GitHub repo](https://github.com/NHSDigital/nrlf-lambda-pipeline) |
| Lambda Logging Package | Source code for the lambda logging utility | [GitHub repo](https://github.com/NHSDigital/nrlf-lambda-logging) |

We currently don't have any open source client libraries or sample code for this API. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/107439/client-libraries-and-reference-implementations).

The source code for the PDS FHIR back end (the Core Spine source code) is not currently in the open. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/466692/open-source-core-spine-including-pds-eps-scr-and-more).

## Environments and testing

| Environment | Base URL |
| ----------------- | ---------------------------------------------------------------------- |
| Sandbox | `https://sandbox.api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |
| Integration test | `https://int.api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |
| Production | `https://api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |

### Sandbox testing

Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
* is for early developer testing
* only covers a limited set of scenarios
* is open access, so does not allow you to test authorisation

For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the
documentation for each endpoint.

Alternatively, you can try out the sandbox using our Postman collection:

Right click the icon and save link as... to save the Postman collection to your device

[![Right click and save link as...](https://run.pstmn.io/button.svg)](https://github.com/NHSDigital/NRLF/raw/main/postman_collection.json)

### Integration testing

Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):

* is for formal integration testing
* includes authorisation

It also includes ready-to-use test data and scenarios. For details [contact us](https://digital.nhs.uk/developer/help-and-support).

For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).

## Onboarding

You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

As part of this process, you need to demonstrate that you can manage risks and that your software conforms technically with the requirements for this API.

Information on this page might impact the design of your software. For details, see [Onboarding support information](https://digital.nhs.uk/developer/api-catalogue/national-record-locator-consumer-fhir/onboarding-support-information).

To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding#using-the-digital-onboarding-portal).

<div class="nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6" aria-label="Highlighted Information">
<div class="nhsd-a-box nhsd-a-box--border-blue">
<div class="nhsd-m-emphasis-box__image-box">
<figure class="nhsd-a-image">
<picture class="nhsd-a-image__picture">
<img src="http://digital.nhs.uk/binaries/content/gallery/icons/play-circle.svg?colour=231f20" alt="" style="object-fit:fill">
</picture>
</figure>
</div>
<div class="nhsd-m-emphasis-box__content-box">
<div data-uipath="website.contentblock.emphasis.content" class="nhsd-t-word-break"><p class="nhsd-t-body">To get started, sign in or create a <a href="http://onboarding.prod.api.platform.nhs.uk/">developer account</a>, then select 'product onboarding'.</p></div>
</div>
</div>
</div>

## Change log

For details of how this API has changed over time, see the [change log](https://github.com/NHSDigital/NRLF/blob/main/CHANGELOG.md).
version: 1.0.0
license:
name: MIT
Expand Down
Loading