Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

Retrieval Read Interaction

Requirements and guidance for record and document retrieval Read Interaction.

Read Request

Retrieval of a referenced record is done through an HTTP(S) GET request to the record URL contained on the pointer.

Retrieval requests should be made through the Spine Secure Proxy (SSP). An exception is made for retrieving publicly accessible contact details (format “Contact Details (HTTP Unsecured)”), for which requests should be made directly.

Consumer and Provider retrieval HTTP requests support the following HTTP request headers:

Header(s) Value Conformance
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
SSP Headers See below for details  

Requests SHOULD NOT require any additional custom headers.

Requests SHOULD NOT require any additional parameters to be passed in the URL.

Read Response

Success:

  • SHALL return a 200 SUCCESS HTTP status code on successful execution of the interaction.
  • SHALL return a response body containing the requested record/document in the format described in the format metadata attributes on the pointer. See Retrieval Formats for further detail.

Failure:

  • SHALL return an error type HTTP status code
  • SHOULD return a response body with diagnostic details.

Retrieval via the SSP

The role of the SSP in retrieval of documents/records is to be a single common authentication and authorisation gateway for all Consumers and Providers.

Retrieval requests via proxy are secured and audited by the SSP. For full technical details, see the SSP specification.

SSP URL

Where a document/record is to be retrieved via the SSP then Consumers MUST pre-fix the content.attachment.url property with the SSP server URL as follows:

GET https://[proxy_server]/https%3A%2F%2Fp1.nhs.uk%2FMentalHealthCrisisPlans%2Fda2b6e8a-3c8f-11e8-baae-6c3be5a609f5

Read a Mental Health Crisis Plan with the logical id of 'da2b6e8a-3c8f-11e8-baae-6c3be5a609f5' from a Provider system located at 'https://p1.nhs.uk' via the Spine Secure Proxy.

Providers MUST not pre-fix the Pointer URL property with the SSP server URL on creation of the pointer.

SSP Headers

The HTTP GET request MUST include a number of Spine specific HTTP headers:

Header Value
Ssp-TraceID Consumer’s TraceID (i.e. GUID/UUID)
Ssp-From Consumer’s ASID
Ssp-To Provider’s ASID
Ssp-InteractionID Spine’s InteractionID.

The interaction ID for retrieving a record referenced in an NRL pointer is specific to the NRL service and is as follows:
urn:nhs:names:services:nrl:DocumentReference.content.read

Please refer to the Spine Secure Proxy Implementation Guide for full technical details.

Guidance on obtaining the provider ASID can be found on the Consumer Guidance page.

Authentication and Authorisation

Systems that interaction with the SSP MUST meet the secure connection requirements of the SSP.

Consumer systems SHALL ensure that users are authenticated and authorised, using an appropriate access control mechanism, before retrieving records and documents. HTTP(S) requests to the SSP for retrieving records and documents will include an access token (JWT) which can be used in Provider systems for auditing purposes. Providers are not required to perform any further authentication or authorisation.

Further detail can be found on the Authentication & Authorisation page.


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