Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Update Interaction

To support the update of NRL pointers

References

Update

Provider interaction to support the update of NRL pointers. The update functionality will be used in cases where a Provider wishes to update a pointer status value, changing it from “current” to “entered-in-error”.

Pre-requisites

In addition to the requirements on this page the general guidance and requirements detailed on the Development Guidance page SHALL be followed when using this interaction.

Update Request Headers

Provider API update 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

Update Operation

Provider systems SHALL construct a FHIRPath PATCH Parameters resource and submit this to NRL using the FHIR RESTful patch interaction.

PATCH [baseUrl]/DocumentReference/da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142

Update the DocumentReference resource status for a pointer with the logical id of 'da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142'.

The API supports the conditional update interaction which allows a provider to update a pointer using the masterIdentifier so they do not have to persist or query for the NRL generated logical id for the pointer. The query parameters should be used as shown:

PATCH [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&identifier=urn:ietf:rfc:3986%7Curn:oid:1.3.6.1.4.1.21367.2005.3.71

Update the DocumentReference resource status for a pointer with a subject and identifier.

[nhsNumber] - The NHS number of the patient whose DocumentReferences the client is requesting

[system] - The namespace of the masterIdentifier value that is associated with the DocumentReference(s)

[value] - The value of the masterIdentifier that is associated with the DocumentReference(s)

Providers systems SHALL only update pointers for records where they are the pointer owner (custodian). For all update requests the custodian ODS code in the DocumentReference resource SHALL be affiliated with the Client System ASID value in the fromASID HTTP request header sent to the NRL.

The FHIRPath PATCH operation must be encoded in a Parameters resource as follows:

  • A single operation as a Parameter named “operation”
  • The single parameter has a series of mandatory parts, with required values as listed in the table below:
Parameter Type Required Value
Type code replace
Path string DocumentReference.status
Value string entered-in-error

Only the first parameter within the Parameters resource will be used to perform a PATCH. Any additional parameters included within the request will not be processed. Further detail on the validation of the Parameters resource can be found in the error handling guidance.

XML and JSON eaxmples of the FHIRPath Parameters resource are shown below.

XML FHIRPath PATCH Parameters resource

<Parameters
    xmlns="http://hl7.org/fhir">
    <parameter>
        <name value="operation"/>
        <part>
            <name value="type"/>
            <valueCode value="replace"/>
        </part>
        <part>
            <name value="path"/>
            <valueString value="DocumentReference.status"/>
        </part>
        <part>
            <name value="value"/>
            <valueString value="entered-in-error"/>
        </part>
    </parameter>
</Parameters>

JSON FHIRPath PATCH Parameters resource

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "replace"
                },
                {
                    "name": "path",
                    "valueString": "DocumentReference.status"
                },
                {
                    "name": "value",
                    "valueString": "entered-in-error"
                }
            ]
        }
    ]
}

Response

Success:

  • SHALL return a 200 SUCCESS HTTP status code on successful execution of the interaction and the entry has been successfully updated in the NRL.
  • SHALL return a response body containing a payload with an OperationOutcome resource that conforms to the ‘Operation Outcome’ core FHIR resource. See table below.
  • When a resource has been updated it will have a versionId of 2.

The table summarises the update interaction HTTP response code and the values expected to be conveyed in the successful response body OperationOutcome payload:

HTTP Code issue-severity issue-type Details.Code Details.Display Details.Text Diagnostics
200 information informational RESOURCE_UPDATED Resource has been updated Spine message UUID Successfully updated resource DocumentReference

Failure:

The following errors can be triggered when performing this operation:


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