Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Read Interaction

To support retrieval of an NRL pointer

References

Read

API to support the retrieval of a single NRL pointer. This functionality is available for consumers and providers.

Read Request Headers

Consumer and Provider API read 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. MAY
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens (JWT) for details. MUST
fromASID Client System ASID MUST
toASID The Spine ASID MUST

Read Operation

The read interaction allows a consumer or provider to retrieve a single pointer (DocumentReference) by logical ID. The consumer or provider must issue an HTTP GET as shown:

Note the status of the pointer must be “current” for the pointer to be retrieved.

Read Response

Success:

  • SHALL return a 200 SUCCESS HTTP status code on successful execution of the interaction.
  • SHALL return a response body containing a DocumentReference resource which conforms to the ‘NRL-DocumentReference-1’ profile and has the status “current”.

Example Successful Response:

<DocumentReference>
    <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
    </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 (record artifact)"/>
        </coding>
    </type>
    <class>
        <coding>
            <system value="http://snomed.info/sct"/>
            <code value="734163000"/>
            <display value="Care plan (record artifact)"/>
        </coding>
    </class>
    <subject>
        <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"/>
    </subject>
    <created value="2016-03-08T15:26:00+01:00"/>
    <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/p1.nhs.uk/MentalhealthCrisisPlanReportRGD.pdf"/>
            <title value="Mental health Crisis Plan Report"/>
            <creation value="2016-03-08T15:26:00+01:00"/>
        </attachment>
        <format>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
            <code value="direct:https://www.iso.org/standard/63534.html"/>
            <display value="PDF (Publicly accessible)"/>
        </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="892811000000109"/>
                <display value="Adult mental health service"/>
            </coding>
        </practiceSetting>
    </context>
</DocumentReference>

Failure:

The following errors can be triggered when performing this operation:

Example Scenario

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

Request Query

Return DocumentReference resource (pointer) with logical ID 0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261. The format of the response body will be XML.

cURL

curl -H 'Accept: application/fhir+xml' -H 'Authorization: BEARER [token]' -X GET  '[baseUrl]/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261'

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

Pointer (DocumentReference) Returned:
  • HTTP 200-Request was successfully executed
  • DocumentReference that conforms to the NRL-DocumentReference-1 profile.
<DocumentReference>
    <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"/>
    </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 (record artifact)"/>
        </coding>
    </type>
    <class>
        <coding>
            <system value="http://snomed.info/sct"/>
            <code value="734163000"/>
            <display value="Care plan (record artifact)"/>
        </coding>
    </class>
    <subject>
        <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"/>
    </subject>
    <created value="2016-03-08T15:26:00+01:00"/>
    <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/p1.nhs.uk/MentalhealthCrisisPlanReportRGD.pdf"/>
            <title value="Mental health Crisis Plan Report"/>
            <creation value="2016-03-08T15:26:00+01:00"/>
        </attachment>
        <format>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
            <code value="direct:https://www.iso.org/standard/63534.html"/>
            <display value="PDF (Publicly accessible)"/>
        </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="892811000000109"/>
                <display value="Adult mental health service"/>
            </coding>
        </practiceSetting>
    </context>
</DocumentReference>
No Record (pointer) Matched:
<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="warning"/>
        <code value="not-found"/>
        <details>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"/>
                <code value="NO_RECORD_FOUND"/>
                <display value="No record found"/>
            </coding>
        </details>
        <diagnostics value="DocumentReference not found"/>
    </issue>
</OperationOutcome>
Error Response (OperationOutcome) Returned:
<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="warning"/>
        <code value="invalid"/>
        <details>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"/>
                <code value="BAD_REQUEST"/>
                <display value="Bad Request"/>
            </coding>
        </details>
        <diagnostics value="DocumentReference status is not 'current'"/>
    </issue>
</OperationOutcome>

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


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