NHS Digital FHIR Implementation Guide (Retired - 2.1.50)

• Where a request maps to a standard FHIR operation, the standard operation SHOULD be used.

Use of standard FHIR RESTful operations makes implementation simpler for clients using standard FHIR libraries and tools, so should be used where possible.

This is appropriate where a server wants to allow resources to be accessed or updated in a way that aligns with the standard operations defined in the FHIR standard. Examples of use-cases where standard RESTful operations may be appropriate:

• Querying for appointment slots.
• Booking an appointment, and updating the associated slot to make it unavailable for others to book.
• Retrieving medications and including the associated patient resources.

In addition, FHIR provides a mechanism to define custom operations. FHIR custom operations follow an RPC architectural model. Ideally APIs should seek to avoid a mixture of architectural styles however it is recognised that deviations from the RESTful model are applicable in certain circumstances.

• More complex and behaviours involving updates to multiple resources or complex querying or composition of resources MAY use an RPC-style FHIR Operation.

Examples of cases where a custom operation may be appropriate:

• Where the server needs to play an active role in formulating the content of the response, not merely return existing information.
• Where the intended purpose is to cause side effects such as the modification of existing resources, or creation of new resources.
• Where a request requires multiple resources to be changed under the control of the client as part of a single atomic transaction.
• When unusual or bespoke behaviours are required which can't easily be achieved using RESTful operations.
• Where there is a requirement to bring back multiple resource types where each resource type had its own specific selection criteria, perhaps also with each of the resources also bringing back associated linked resources.