For more in depth discussion on this subject please see the HL7 R4 page providing guidance on restful API’s

General Principles

When a booking provider is processing create and update operations, there is no general-purpose method to make merging with existing content or altering the content by business rules safe or predictable. Even though the resource may be retrieved by the consumer systems through a read interaction prior to attempting an update for example, the resource on the provider may be different. These differences may arise for several reasons:

  • The provider merged updated content with existing content
  • The provider applied business rules and altered the content
  • The provider does not fully support all the features or possible values of the resource

This is why all updates (such as when performing a cancel operation) must be version aware. However, to further mitigate the problems of inconsistencies in the content between client and server, the following rules can be applied:

  • The provider must support a read interaction for any resource it accepts update interactions on
  • Before updating, the consumer must read the latest version of the resource
  • The consumer applies the changes it wants to the resource, leaving other information intact
  • The consumer writes the result back as an update interaction, and is able to handle a 409 (conflict) or 412 (precondition failed) response (usually by trying again) If consumers follow this pattern, then information from other systems that they do not understand will be maintained through the update.

Both consumer and provider systems should clearly document how transaction integrity is handled by specifying in the documentation inside the CapabilityStatement

Handling a special case - duplicates arising from retrys

In order to further assist in maintaining the integrity of transactions some custom headers are available. It is expected that two of the custom headers defined in the FHIR standard are used for this purpose:

  • X-Request-ID is a unique id for the request/response assigned by either client or server. Request: assigned by the client. Response: assigned by the server
  • X-Correlation-ID a client assigned request id echoed back in the response

Additionally there is a specific scenario that might arise that needs to be mitigated, this is when a provider accepts a booking via a POST and the 200 OK response is not received by the Consumer. In this scenario the consumer system is entitled to re-try the POST request until the OK response is recieved or the attempt is abandoned. Under these circumstances, this might lead to duplicate appointments being made on the Provider system. Therefore the X-Request-ID and X-Correlation-ID can be used to prevent this.

When the consumer makes a request it will assign an X-request-ID to the header. When the provider system recieves the request, it will retrieve the X-request-ID and set the X-Correlation-ID to that value (to echo back). It will then generate an X-Request-ID of its own and both X-Headers will be assigned to the response.

The following diagram illustrates this:

Therefore the following requirements apply:

For the booking consumer:

  • each request must include an X-request-ID
  • any retry of the same request must include the original X-request-ID unchanged
  • received responses should be correlated with the originating request
  • receved X-request-ID and X-Correlation-ID must be placed in a log or audit trail against the booking attempt

For the booking provider:

  • each response must include an X-request-ID
  • each response must echo the request X-request-ID as the X-Correlation-ID
  • The X-request-ID from the request message must be used to verify a previous successful booking has not already been made from a request with this X-request-ID
  • receved X-request-ID and X-Correlation-ID must be placed in a log or audit trail against the booking attempt