Merge pull request #55 from NHSDigital/feature/NRLF-402_oas_feedback_…

…narrative [NRLF-402] OAS Feedback (Narrative)
NHSDigital · Mar 24, 2023 · 4b2dcf3 · 4b2dcf3
2 parents 4ba22f8 + f0fbce1
commit 4b2dcf3
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 27 deletions.
diff --git a/specification/nrl-consumer-api.yaml b/specification/nrl-consumer-api.yaml
@@ -7,16 +7,22 @@ info:
   description: |
     ## Overview
 
-    The National Record Locator (NRL) enables organisations to share Patient data nationwide.  It acts as an Index, or Directory, of patient data.  Rather than handling the data itself it shares pointers held in partner systems, using the FHIR R4 DocumentReference standard.
+    The National Record Locator (NRL) enables organisations to share Patient data nationwide.  It acts as an Index, or
+    Directory, of patient data.  Rather than handling the data itself it shares pointers held in partner systems, using
+    the [FHIR R4 DocumentReference](http://hl7.org/fhir/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.
+    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.
+    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.
 
@@ -28,7 +34,8 @@ info:
 
     ### What has changed?
 
-    This service is a replacement for the existing [National Record Locator (NRL)](https://digital.nhs.uk/services/national-record-locator).
+    This service is a replacement for the existing [National Record Locator
+    (NRL)](https://digital.nhs.uk/services/national-record-locator).
 
     * Upgraded from FHIR STU3 to R4.
     * Improved performance and scalability.
@@ -65,29 +72,35 @@ info:
 
     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).
+    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.
+    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 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).
+    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 `/Immunization` not `/immunisations`
+    * 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
 
@@ -106,11 +119,10 @@ info:
 
     ## Environments and testing
 
-    | Environment       | Base URL                                                               |
-    | ----------------- | ---------------------------------------------------------------------- |
-    | Sandbox           | `https://sandbox.api.service.nhs.uk/nrl-consumer-api/FHIR/R4/`     |
-    | Integration test  | `https://int.api.service.nhs.uk/nrl-consumer-api/FHIR/R4/`         |
-    | Production        | `https://api.service.nhs.uk/nrl-consumer-api/FHIR/R4/`             |
+    | Environment       | Base URL                                                       |
+    | ----------------- | -------------------------------------------------------------- |
+    | Sandbox           | `https://sandbox.api.service.nhs.uk/nrl-consumer-api/FHIR/R4/` |
+    | Integration test  | `https://int.api.service.nhs.uk/nrl-consumer-api/FHIR/R4/`     |
 
     ### Sandbox testing
 
@@ -119,7 +131,8 @@ info:
     * 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.
+    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:
 
@@ -138,11 +151,13 @@ info:
 
     ## 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.
+    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.
 
     This API uses our online digital onboarding process.
 
-    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.
+    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-api/onboarding-support-information).
 
@@ -164,7 +179,7 @@ servers:
 paths:
   /DocumentReference:
     get:
-      summary: Search (GET)
+      summary: Retrieve patient's document pointers (GET)
       operationId: searchDocumentReference
       parameters:
         - $ref: "#/components/parameters/subject"
@@ -176,7 +191,7 @@ paths:
         - $ref: "#/components/parameters/correlationId"
       responses:
         "200":
-          description: Search successful response
+          description: Successful response
           content:
             application/fhir+json;version=1:
               schema:
@@ -278,10 +293,14 @@ paths:
             X-Request-Id:
               $ref: "#/components/headers/RequestId"
       description: |
-        Search a single Patient's records.
+        Retrieve the document pointers for a single patient.  Your request is constrained by the document pointer types
+        agreed during onboarding.  The results can also be filtered to return documents by a given `type` and/or created
+        by a given `custodian`.
+
+        This operation is also available as a http POST, which is the preferred method (see below).
   /DocumentReference/_search:
     post:
-      summary: Search (POST)
+      summary: Retrieve patient's document pointers (POST)
       operationId: searchPostDocumentReference
       parameters:
         - $ref: "#/components/parameters/odsCode"
@@ -392,15 +411,20 @@ paths:
             X-Request-Id:
               $ref: "#/components/headers/RequestId"
       description: |
-        Search a single Patient's records, but implemented as a POST operation
-        because of limitations associated with GET:
+        Retrieve the document pointers for a single patient.  Your request is constrained by the document pointer types
+        agreed during onboarding.  The results can also be filtered to return documents by a given `type` and/or created
+        by a given `custodian`.
+
+        This operation is also available as a http GET for convenience (see above), but POST is preferred for the
+        following reasons.
 
         * query string parameters are visible on the network and in logs, and may have privacy implications for consumers.
         * GET operations can be cached by intermediary network infrastructure, such as CDNs, routers and proxies.
-        * URLs have a maximum length of 2,048 characters which complex searches can exceed.  NRL does not currently exceed this limit, but may evolve in the future.
+        * URLs have a maximum length of 2,048 characters which complex searches can exceed.  NRL does not currently
+        exceed this limit, but may evolve in the future.
   /DocumentReference/{id}:
     get:
-      summary: Read
+      summary: Get a single document pointer
       operationId: readDocumentReference
       parameters:
         - $ref: "#/components/parameters/id"
@@ -486,7 +510,8 @@ paths:
             X-Request-Id:
               $ref: "#/components/headers/RequestId"
       description: |
-        Read a single DocumentReference record using the `DocumentReference.id`
+        Read a single document pointer by specifying the `DocumentReference.id`.  Note that you will only be able to
+        retrieve document pointers that have the `type` that was agreed during the [on-boarding](#Onboarding) process.
 components:
   requestBodies:
     DocumentReference:
@@ -1207,7 +1232,6 @@ components:
       example: "https://fhir.nhs.uk/Id/ods-organization-code|Y05868"
     RequestQueryType:
       type: string
-      pattern: ^http\:\/\/snomed\.info\/sct\|(\d+)$
       example: "http://snomed.info/sct|736253002"
     NextPageToken:
       type: string

diff --git a/specification/nrl.png b/specification/nrl.png