References
NHS Digital Profile: NRL-DocumentReference-1 |
HL7 FHIR STU3 Resource(s): DocumentReference |
User Stories: - |
Search
Consumer interaction to support a parameterised search of the NRL. The search interaction is a FHIR RESTful search interaction.
Prerequisites
In addition to the requirements on this page, the general guidance and requirements detailed on the Development Overview page MUST be followed when using this interaction.
Search Request Headers
Consumer 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, if set, this must be either application/fhir+json or application/fhir+xml . |
OPTIONAL |
Authorization |
The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see the JSON Web Token Guidance page for details. |
REQUIRED |
fromASID |
Client System ASID. | REQUIRED |
toASID |
The Spine ASID. | REQUIRED |
Search DocumentReference
GET [baseUrl]/STU3/DocumentReference?[searchParameters]
Search Parameters
This implementation guide outlines the search parameters for the DocumentReference
resource in the table below:
Name | Type | Description | Path |
---|---|---|---|
_id |
id | Logical ID of the resource. | DocumentReference.id |
subject |
reference | Subject (patient) of the DocumentReference . |
DocumentReference.subject (Patient NHS Number) |
custodian |
reference | Organisation which maintains the DocumentReference . |
DocumentReference.custodian (Organisation ODS Code) |
type |
Coding | Information type (SNOMED CT). | DocumentReference.type.coding |
A search is made using either the _id
or subject
search parameter.
- The
_id
search parameter MUST NOT be used in conjunction with any other search parameter (with the exception of the_format
parameter). - The
custodian
and/ortype
search parameters can only be used in conjunction with thesubject
search parameter to form a combination search query.
|
) character must be percent encoded (%7C
)._id
The _id
search parameter refers to the logical ID of the DocumentReference
resource.
Functionally this search is the equivalent to a simple pointer read operation.
See _id
for details on this search parameter. The _id
search parameter can be used as follows:
GET [baseUrl]/STU3/DocumentReference?_id=[id]
GET [baseUrl]/STU3/DocumentReference?_id=da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142
Search for the DocumentReference resource for a pointer with the logical ID of 'da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142'
The _id
search parameter cannot be used in conjunction with any other search parameter (with the exception of the _format
parameter.)
subject
See reference
for details on this search parameter. The subject
search parameter can be used as follows:
GET [baseUrl]/STU3/DocumentReference?subject=[reference]
The subject
search parameter MUST follow the format:
https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]
GET [baseUrl]/STU3/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210
Return all DocumentReference resources for a patient with an NHS Number of 9876543210.
subject
and type
The subject
and type
search parameters can be used as follows:
GET [baseUrl]/STU3/DocumentReference?subject=[reference]&type.coding=[system]%7C[code]
The subject
search parameter MUST follow the format:
https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]
The type
search parameter MUST follow the format:
[system]|[code]
GET [baseUrl]/STU3/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210&type.coding=http%3A%2F%2Fsnomed.info%2Fsct%7C736253002
Return all DocumentReference resources for a patient with an NHS Number of 9876543210 and pointer type 'Mental health crisis plan'.
subject
and custodian
The subject
and custodian
search parameters can be used as follows:
GET [baseUrl]/STU3/DocumentReference?subject=[reference]&custodian=[reference]
The subject
search parameter MUST follow the format:
https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]
The custodian
search parameter MUST follow the format:
https://directory.spineservices.nhs.uk/STU3/Organization/[ODS Code]
GET [baseUrl]/STU3/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210&custodian=https%3A%2F%2Fdirectory.spineservices.nhs.uk%2FSTU3%2FOrganization%2FRR8
Return all DocumentReference resources for a patient with an NHS Number of 9876543210 and pointer owner with ODS code RR8.
Search Response
Success
A successful execution of the search interaction will:
- return a
200
OK HTTP status code. - return a
Bundle
response boby of typesearchset
, containing either:- A
0
(zero) total value indicating no records matched the search criteria, i.e. an emptyBundle
.
Note: The NRL service will ONLY return an empty bundle if a Spine Clinicals record exists and there is no DocumentReference for that specific Clinicals record.- One or more
DocumentReference
resources (with acurrent
status) that conform to the NRLDocumentReference
FHIR profile.- The current
versionId
will be included. - If
masterIdentifier
and/orrelatesTo
are set, they will be included.
- The current
Note: The version of the pointer model (FHIR profile) will be indicated in theDocumentReference.meta.profile
metadata attribute for each pointer (see FHIR Resources & References). A ‘Bundle’ may contain pointers which conform to different versions of the pointer model. - A
Failure
The following errors can be triggered when performing this operation:
Example: Single Pointer Response
- Request was successfully executed (
200
OK HTTP status). - Response body is a
Bundle
resource of typesearchset
containing 1DocumentReference
resource conforming to theNRL-DocumentReference-1
profile.
Example: Multiple Pointers Response
- Request was successfully executed (
200
OK HTTP status). - Response body is a
Bundle
resource of typesearchset
containing 2DocumentReference
resources conforming to theNRL-DocumentReference-1
profile.
Example: No Pointers Response
- Request was successfully executed (
200
OK HTTP status). - Response body is an empty
Bundle
resource of typesearchset
containing 0 (zero)DocumentReference
resources indicating no record was matched.
Explore the NRL
You can explore and test the search interaction using Swagger in the NRL API Reference Implementation.