Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Search Interaction

To support parameterised search of the NRL.

References

Consumer interaction to support parameterised search of the NRL.

Pre-requisites

In addition to the requirements on this page the general guidance and requirements detailed on the Development Guidance page MUST be followed when using this interaction.

Search Request Headers

Consumer and Provider API search requests support the following HTTP request headers:

Header Value Conformance
Accept The Accept header indicates the format of the response the client is able to understand, this will be one of the following application/fhir+json or application/fhir+xml. See the RESTful API Content types section. OPTIONAL
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens (JWT) for details. REQUIRED
fromASID Client System ASID REQUIRED
toASID The Spine ASID REQUIRED

Search DocumentReference

Though the NRL does not keep a version history of each DocumentReference, each one does hold a versionId.

In responding to a search request, the NRL server will populate the versionId of each matching DocumentReference.

Search Parameters

This implementation guide outlines the search parameters for the DocumentReference resource in the table below.

Name Type Description Conformance Path
_id token The logical id of the resource RECOMMENDED DocumentReference.id
custodian reference Organisation which maintains the document reference OPTIONAL DocumentReference.custodian
(Organisation ODS Code)
subject reference Who/what is the subject of the document RECOMMENDED DocumentReference.subject
(Patient NHS Number)
type token Kind of document (SNOMED CT) OPTIONAL DocumentReference.type
_summary Summary Total number of matching results OPTIONAL N/A

When the _id search parameter is used by a client it MUST only be used as a single search parameter and MUST not be used in conjunction with any other search parameter to form part of a combination search query with the exception of ‘_format’ parameter.

When the subject parameter is used by a client it MAY be used in conjunction with the custodian and type search parameters to form a combination search query. The custodian and type search parameters MUST only be used to form combination search queries.

_id

The search parameter _id refers to the logical id of the DocumentReference resource and can be used when the search context specifies the DocumentReference resource type.

Functionally this search is the equivalent to a simple pointer read operation.

See _id for details on this parameter. The _id parameter can be used as follows:

When the _id search parameter is used by a client, this search parameter MUST only be used as a single search parameter and MUST not be used in conjunction with any other parameter to form part of a combination search query with the exception of ‘_format’ parameter.

subject

See reference for details on this parameter. The subject parameter can be used as follows:

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210

Return all DocumentReference resources for a patient with a NHS Number of 9876543210

subject and custodian

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&custodian=https://directory.spineservices.nhs.uk/STU3/Organization/RR8

Return all DocumentReference resources for a patient with a NHS Number of 9876543210 and a pointer provider ODS code of RR8.

subject and type

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&type.coding=http://snomed.info/sct%7C736253002

Return all DocumentReference records for a patient with NHS Number of 9876543210 and a pointer type of Mental Health Crisis plan.

_summary

The search parameter _summary allows the client to retrieve the number of DocumentReferences that match a given search.

See _summary for details on this parameter. The _summary parameter can be used as follows:

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&_summary=count

Return a count of resources for a patient with a NHS Number of 9876543210

The _summary search parameter must be set to the value ‘count’ to retrieve the number of matching results. Other FHIR values for this search parameter are not supported.

Search Response

Success:

  • MUST return a 200 OK HTTP status code on successful execution of the interaction.
  • MUST return a Bundle of type searchset, containing either:

    • One or more DocumentReference resources that conform to the NRL DocumentReference FHIR profile and that have the status value of “current”.

    • A ‘0’ (zero) total value indicating no record was matched i.e. an empty ‘Bundle’.

  • Where a documentReference is returned, it MUST include the versionId of the current version of the documentReference resource

  • When a Consumer retrieves a DocumentReference if the masterIdentifier is set then it SHOULD be included in the returned DocumentReference

  • When a Consumer retrieves a DocumentReference if the relatesTo is set then it SHOULD be included in the returned DocumentReference

Failure:

The following errors can be triggered when performing this operation:

Example Scenario

An authorised NRL Consumer searches for a patient’s relevant health record using the NRL to discover potentially vital information to support a patient’s emergency crisis care.

Request Query

Return all DocumentReference resources (pointers) for a patient with a NHS Number of 9876543210. The format of the response body will be XML.

cURL

curl -H 'Accept: application/fhir+xml' -H 'Authorization: BEARER [token]' -X GET  '[baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&_format=xml'

Query Response Http Headers

HTTP/1.1 200 OK
Server: nginx/1.10.0 (Ubuntu)
Date: Mon, 19 Jun 2017 08:36:12 GMT
Content-Type: application/fhir+xml;charset=utf-8
Last-Modified: Mon, 19 Jun 2017 08:36:12 GMT

Query Response

Single Pointer (DocumentReference) Returned:
  • HTTP 200-Request was successfully executed
  • Bundle resource of type searchset containing a total value ‘1’ DocumentReference resource that conforms to the NRL-DocumentReference-1 profile.
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="dd9724d1-7b61-44e2-9023-b72e6b966018-76563212455590986546"/>
    <type value="searchset"/>
    <total value="1"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210"/>
    </link>
    <entry>
        <fullUrl value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"/>
        <resource>
            <DocumentReference>
                <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"/>
                <meta>
                    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
                    <version value="1"/>
                    <lastUpdated value="2016-03-08T15:26:00+01:00"/> 
                </meta>
                <masterIdentifier>
                    <system value="urn:ietf:rfc:3986"/>
                    <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.7"/>
                </masterIdentifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="736253002"/>
                        <display value="Mental health crisis plan"/>
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="734163000"/>
                        <display value="Care plan"/>
                    </coding>
                </class>
                <subject>
                    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"/>
                </subject>
                <indexed value="2016-03-08T15:26:01+01:00"/>
                <author>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RGD"/>
                </author>
                <custodian>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RR8"/>
                </custodian>
                <relatesTo>
                    <code value="replaces"/>
                    <target>
                        <identifier>
                            <system value="urn:ietf:rfc:3986"/>
                            <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.6"/>
                        </identifier>
                    </target>
                </relatesTo>
                <content>
                    <attachment>
                        <contentType value="application/pdf"/>
                        <url value="https://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.pdf"/>
                        <creation value="2016-03-08T15:26:00+01:00"/>
                    </attachment>
                    <format>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1"/>
                        <code value="urn:nhs-ic:unstructured"/>
                        <display value="Unstructured Document"/>
                    </format>
                    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1">
                        <valueCodeableConcept>
                            <coding>
                                <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1"/>
                                <code value="static"/>
                                <display value="Static"/>
                            </coding>
                        </valueCodeableConcept>
                    </extension>
                </content>
                <context>
                    <period>
                        <start value="2016-03-07T13:34:00+01:00"/>
                    </period>
                    <practiceSetting>
                        <coding>
                            <system value="http://snomed.info/sct"/>
                            <code value="708168004"/>
                            <display value="Mental health service"/>
                        </coding>
                    </practiceSetting>
                </context>
            </DocumentReference>
        </resource>
        <search>
            <mode value="match"/>
        </search>
    </entry>
</Bundle>
Multiple Pointers (DocumentReference) Returned:
  • HTTP 200-Request was successfully executed
  • Bundle resource of type searchset containing a total value ‘2’ DocumentReference resources that conform to the NRL-DocumentReference-1 profile
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="dd9724d1-7b61-44e2-9023-b72e6b966018-54446768443265458908"/>
    <type value="searchset"/>
    <total value="2"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543211"/>
    </link>
    <entry>
        <fullUrl value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-58778905432232112312"/>
        <resource>
            <DocumentReference>
                <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-58778905432232112312"/>
                <meta>
                    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
                    <version value="1"/>
                    <lastUpdated value="2016-03-08T15:26:00+01:00"/> 
                </meta>
                <masterIdentifier>
                    <system value="urn:ietf:rfc:3986"/>
                    <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.11"/>
                </masterIdentifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="736253002"/>
                        <display value="Mental health crisis plan"/>
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="734163000"/>
                        <display value="Care plan"/>
                    </coding>
                </class>
                <subject>
                    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543211"/>
                </subject>
                <indexed value="2018-07-01T15:26:01+01:00"/>
                <author>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RGD"/>
                </author>
                <custodian>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RR8"/>
                </custodian>
                <content>
                    <attachment>
                        <contentType value="application/pdf"/>
                        <url value="https://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisTeam"/>
                        <creation value="2018-07-01T15:26:00+01:00"/>
                    </attachment>
                    <format>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1"/>
                        <code value="urn:nhs-ic:record-contact"/>
                        <display value="Contact details (HTTP Unsecured)"/>
                    </format>
                    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1">
                        <valueCodeableConcept>
                            <coding>
                                <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1"/>
                                <code value="static"/>
                                <display value="Static"/>
                            </coding>
                        </valueCodeableConcept>
                    </extension>
                </content>
                <context>
                    <period>
                        <start value="2017-05-12T13:34:00+01:00"/>
                    </period>
                    <practiceSetting>
                        <coding>
                            <system value="http://snomed.info/sct"/>
                            <code value="708168004"/>
                            <display value="Mental health service"/>
                        </coding>
                    </practiceSetting>
                </context>
            </DocumentReference>
        </resource>
        <search>
            <mode value="match"/>
        </search>
    </entry>
    <entry>
        <fullUrl value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/5303c09e-de28-4622-9416-62ab0b22e15a-54598780989231213433"/>
        <resource>
            <DocumentReference>
                <id value="5303c09e-de28-4622-9416-62ab0b22e15a-54598780989231213433"/>
                <meta>
                    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
                    <version value="1"/>
                    <lastUpdated value="2016-03-08T15:26:00+01:00"/> 
                </meta>
                <masterIdentifier>
                    <system value="urn:ietf:rfc:3986"/>
                    <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.10"/>
                </masterIdentifier>
                <status value="current"/>
                <type>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="736253002"/>
                        <display value="Mental health crisis plan"/>
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="734163000"/>
                        <display value="Care plan"/>
                    </coding>
                </class>
                <subject>
                    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543211"/>
                </subject>
                <indexed value="2018-07-02T11:25:01+01:00"/>
                <author>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RGD"/>
                </author>
                <custodian>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RR8"/>
                </custodian>
                <relatesTo>
                    <code value="replaces"/>
                    <target>
                        <identifier>
                            <system value="urn:ietf:rfc:3986"/>
                            <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.9"/>
                        </identifier>
                    </target>
                </relatesTo>
                <content>
                    <attachment>
                        <contentType value="application/pdf"/>
                        <url value="https://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.pdf"/>
                        <creation value="2016-03-08T15:26:00+01:00"/>
                    </attachment>
                    <format>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1"/>
                        <code value="urn:nhs-ic:unstructured"/>
                        <display value="Unstructured Document"/>
                    </format>
                    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1">
                        <valueCodeableConcept>
                            <coding>
                                <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1"/>
                                <code value="static"/>
                                <display value="Static"/>
                            </coding>
                        </valueCodeableConcept>
                    </extension>
                </content>
                <context>
                    <period>
                        <start value="2016-03-07T13:34:00+01:00"/>
                        <end value="2017-02-13T14:11:00+01:00"/>
                    </period>
                    <practiceSetting>
                        <coding>
                            <system value="http://snomed.info/sct"/>
                            <code value="708168004"/>
                            <display value="Mental health service"/>
                        </coding>
                    </practiceSetting>
                </context>
            </DocumentReference>
        </resource>
        <search>
            <mode value="match"/>
        </search>
    </entry>
</Bundle>
No Record (pointer) Matched:
  • HTTP 200-Request was successfully executed
  • Empty bundle resource of type searchset containing a ‘0’ (zero) total value indicating no record was matched
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="de258b7f-2f0b-4b41-afcb-964d9995fd4f-65447656980012115439"/>
    <type value="searchset"/>
    <total value="0"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543213"/>
    </link>
</Bundle>
Error Response (OperationOutcome) Returned:
  • HTTP 400-Bad Request. Invalid Parameter.
  • OperationOutcome resource that conforms to the ‘Spine-OperationOutcome-1’ profile if the search cannot be executed (not that there is no match)
<OperationOutcome
    xmlns="http://hl7.org/fhir">
    <id value="5a4171ac-486e-11e8-9ffc-6c3be5a609f5-34326129638901216693"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1"/>
    </meta>
    <issue>
        <severity value="error"/>
        <code value="invalid"/>
        <details>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"/>
                <code value="INVALID_PARAMETER"/>
                <display value="Invalid parameter"/>
            </coding>
        </details>
        <diagnostics value="The given resource URL does not conform to the expected format - https://demographics.spineservices.nhs.uk/STU3/Patient/[NHS Number]"/>
    </issue>
</OperationOutcome>

See the general API guidance for all HTTP Error response codes supported by the NRL.

_summary=count response:
  • Response body MUST return a valid XML or JSON formatted Bundle of type searchset, containing a bundle that reports the total number of resources that match in Bundle.total, but with no entries, and no prev/next/last links. Note that the Bundle.total only include the total number of matching DocumentReferences.

Examples

  • 3 DocumentReferences exist for patient with NHS number passed into the search
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="de258b7f-2f0b-4b41-afcb-964d9995fdf-98874345667801234356"/>
    <type value="searchset"/>
    <total value="3"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543214&amp;_summary=count"/>
    </link>
</Bundle>
  • 0 DocumentReferences exist for patient with NHS number passed into the search
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="de258b7f-2f0b-4b41-afcb-964d5995fd4f-16547321986190065387"/>
    <type value="searchset"/>
    <total value="0"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543213&amp;_summary=count"/>
    </link>
</Bundle>

Code Examples

GET Pointers with C

The following code samples are taken from the NRL Demonstrator application which has both Consumer and Provider client implementations built in. More information about the design solution can be found on the NRL Demonstrator Wiki

First we generate a base pointer request model that includes the patients NHS Number used for the subject parameter. The NHS Number is obtained through a stub PDS Trace performed within the Demonstrator Consumer system.

Then we call our DocumentReference service GetPointersBundle method which will build a GET command request and then start the call to the NRL API.

This Github Sample is by nhsconnect
Demonstrator/Demonstrator.Services/Service/Nrls/PointerService.cs#L34-L36 view raw 
var pointerRequest = NrlsPointerRequest.Search(request.OrgCode, request.Id, null, request.Asid, null);

var pointerResponse = await _docRefService.GetPointersBundle(pointerRequest);

Once we have received pointers from the NRL when then look up the custodian (and author) organisation details using the ODS Code’s held within each pointer via a stub ODS lookup. We can then present actual organisation details to the end users.

Calling the NRL
Using our GET command request model we create a connection to the NRL using HttpClient.

You can view the common connection code example here.

Explore the NRL
You can explore and test the NRL GET command using Swagger in the NRL API Reference Implementation.

Tags: rest fhir api noccprofile

All content is available under the Open Government Licence v3.0, except where otherwise stated