Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Delete Interaction

To support the deletion of NRL pointers.

References

Delete

API to support the deletion of NRL pointers. This functionality is only available for providers.

Delete Request Headers

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

Delete Operation

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

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

Delete by ‘id’

The API supports the delete 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 DELETE as shown:

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

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

Conditional Delete by ‘id’

The API supports the conditional delete by id interaction which allows a provider to delete an existing pointer based on the search parameter _id which refers to 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 DELETE as shown:

DELETE [baseUrl]/DocumentReference?_id=da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142

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

Conditional Delete by ‘masterIdentifier’

The API supports the conditional delete by masterIdentifier interaction which allows a provider to delete an existing pointer using the masterIdentifier so they do not have to persist or query for the NRL generated logical id for the Pointer.

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

[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)

DELETE [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

Delete the DocumentReference resource for a pointer with a subject and identifier.

Delete Response

The 'delete' interaction removes an existing resource. The interaction is performed by an HTTP DELETE of the DocumentReference resource.

Success:

  • SHALL return a 200 OK HTTP status code on successful execution of the interaction.
  • SHALL return a response body containing a payload with an OperationOutcome resource that conforms to the ‘Spine-OperationOutcome-1’ FHIR profile.

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

HTTP Code issue-severity issue-type Details.Code Details.Display Details.Text Diagnostics
200 information informational RESOURCE_DELETED Resource removed Spine message UUID Successfully removed resource DocumentReference: [url]

Failure:

The following errors can be triggered when performing this operation:

Code Examples

DELETE a Pointer with C#

The following code samples are taken from the NRL Demonstrator application which has both Consumer and Provider client implementations built in. More information about the design solution can be found on the NRL Demonstrator Wiki

First we generate a base pointer request model that includes the pointer logical id used for the _id parameter. The logical id is obtained from a mapping stored within the Demonstrator that maps the Provider system crisis plans to NRL pointers.

Then we call our DocumentReference service DeletePointer method which will build a DELETE command request and then start the call to the NRL API.

Demonstrator/Demonstrator.Services/Service/Epr/CrisisPlanService.cs#L158-L160 view raw
var pointerRequest = NrlsPointerRequest.Delete(pointerMap.NrlsPointerId, request.Asid, request.OrgCode);

var outcome = await _documentReferenceServices.DeletePointer(pointerRequest);


Calling the NRL
Using our DELETE command request model we create a connection to the NRL using HttpClient.

You can view the common connection code example here.

Explore the NRL
You can explore and test the NRL DELETE command using Swagger in our Reference implementation.


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