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. |
REQUIRED |
| 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:
- MUST return a
200SUCCESS HTTP status code on successful execution of the interaction. - MUST 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 more details.
Failure:
- MUST 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 percent encode the content.attachment.url property and prefix it with the SSP server URL as follows:
GET https://[proxy_server]/[percent_encoded_record_url]
For example:
GET https://[proxy_server]/https%3A%2F%2Fp1.nhs.uk%2FMentalHealthCrisisPlans%2Fda2b6e8a-3c8f-11e8-baae-6c3be5a609f5
This request would fetch 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.
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 Interaction ID. 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 interact with the SSP MUST meet the secure connection requirements of the SSP.
Consumer systems MUST 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.
More details can be found on the Authentication & Authorisation page.
