API Update Interaction

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. The update interaction is a FHIR RESTful patch 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.

Update Request Headers

Provider API update requests support the following HTTP request headers:

Update Operation

Providers systems MUST only update pointers for records where they are the pointer owner (custodian).

For all update requests the custodian ODS code in the DocumentReference MUST be affiliated with the Client System ASID value in the fromASID HTTP request header sent to the NRL.

Update by id

The API supports the update by ID interaction, which allows a provider to delete an existing pointer based on the logical ID of the pointer.

The logical ID can be obtained from the Location header which is contained in the create response - see the Create API Interaction for details.

To accomplish this, the provider issues an HTTP PATCH as shown:

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

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

Conditional Update by masterIdentifier

The API supports the conditional update interaction which allows a provider to update a pointer using the masterIdentifier, negating the requirement to persist or query the NRL to obtain the generated logical ID for the pointer.

The query parameters should be used as shown:

• [nhsNumber] - The NHS Number of the patient related to the DocumentReference.
• [system] - The namespace of the masterIdentifier value associated with the DocumentReference.
• [value] - The value of the masterIdentifier associated with the DocumentReference.

PATCH [baseUrl]/STU3/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210%26identifier%3Durn%3Aietf%3Arfc%3A3986%257Curn%3Aoid%3A1.3.6.1.4.1.21367.2005.3.71

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

Request Body

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

The Parameters resource MUST meet the following conditions:

Three part elements are required as follows:

XML FHIRPath PATCH Parameters Resource Example

<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 Example

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

Response

Success

A successful execution of the update interaction will:

• return a 200 OK HTTP status code confirming the entry has been successfully updated in the NRL.
• return a response body containing an OperationOutcome resource (see below for full details).
• increment the resource’s versionId by 1.

OperationOutcome

The OperationOutcome resource in the response body will conform to the Spine-OperationOutcome-1 FHIR resource:

Example success response body (XML)

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="1500ab25-b9e5-4515-9f11-3ca0adddbcce-00000000000000000000" />
  <meta>
    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1" />
  </meta>
  <issue>
    <severity value="information" />
    <code value="informational" />
    <details>
      <coding>
        <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1" />
        <code value="RESOURCE_UPDATED" />
        <display value="Resource has been updated" />
      </coding>
      <text value="911f55e4-d754-4fee-b044-f8aad32ad309" />
    </details>
    <diagnostics value="Successfully updated resource DocumentReference: http://data.developer.nhs.uk/nrls-ri/DocumentReference/5f5247408ae8c40001ba7d90?_format=application%2Fxml" />
  </issue>
</OperationOutcome>

Example success response body (JSON)

{
  "resourceType": "OperationOutcome",
  "id": "1500ab25-b9e5-4515-9f11-3ca0adddbcce-00000000000000000000",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1"
    ]
  },
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1",
            "code": "RESOURCE_UPDATED",
            "display": "Resource has been updated"
          }
        ],
        "text": "911f55e4-d754-4fee-b044-f8aad32ad309"
      },
      "diagnostics": "Successfully updated resource DocumentReference: http://data.developer.nhs.uk/nrls-ri/DocumentReference/5f5247408ae8c40001ba7d90"
    }
  ]
}

Failure

The following errors can be triggered when performing this operation:

• Invalid Request Message
• Invalid Resource
• Invalid Parameter
• Resource Not Found
• Inactive DocumentReference

Explore the NRL

You can explore and test the update interaction using Swagger in the NRL API Reference Implementation.