To support retrieval of an NRL pointer
Important: This site is under active development by NHS Digital and is intended to provide all the technical resources you need to successfully develop APIs. This project is being developed using an agile methodology, so iterative updates to content will be added on a regular basis.
Warning: This site is provided for information only and is intended for those engaged with NHS Digital on the development of APIs. It is advised not to develop against these specifications until a formal announcement has been made.
References
NHS Digital Profile: DocumentReference |
HL7 FHIR STU3 Resource: DocumentReference |
User Stories: - |
Read
Consumer interaction to support the retrieval of a single NRL pointer.
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.
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. |
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 |
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:
GET [baseUrl]/DocumentReference/[id]
GET [baseUrl]/DocumentReference/da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142
Read the DocumentReference resource for a pointer with the logical id of 'da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142'.
Note the status of the pointer must be “current” for the pointer to be retrieved.
Read Response
Success:
- MUST return a
200SUCCESS HTTP status code on successful execution of the interaction. - MUST return a response body containing a DocumentReference resource which conforms to the NRL-DocumentReference-1 FIHR 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"/>
<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>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-1profile.
<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>No Record (pointer) Matched:
- HTTP 404-Not Found. No record found.
- OperationOutcome resource that conforms to the ‘Spine-OperationOutcome-1’ profile
<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:
- HTTP 400-Bad Request.
- OperationOutcome resource that conforms to the ‘Spine-OperationOutcome-1’ profile if the resource cannot be 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.
