The Exchange Paradigms introduce ways of implementing FHIR Resources using RESTful API, messaging and documents.

FHIR is designed to support a wide variety of contexts and architectures which are explored here as Exchange Paradigms for the various Information Sharing Patterns. The most modern and granular paradigm is the RESTful API model. A RESTful API model is based on exposing operations such as create, read, update, delete (CRUD) and stateless access. This access is typically a granular way to access content and helps testing, security and monitoring of the exposed data. An important consideration of the RESTful model is that interactions are driven by the consumer of the data who will pull data by making requests to the provider when they need it. Small requests are expected from the consumer which the provider answers immediately while the consumer maintains state. This makes it possible for the consumer to provide richer experiences for end users.

A 'consumer' refers to either a client system or a person that has a need to retrieve data from a provider.

The Exchange Paradigms are complimentary, each having it’s strengths and weaknesses. A solution may combine Information Sharing Patterns or Exchange Paradigms.

FHIR supports four exchange paradigms when accessing resources:

REST Small, light-weight and loosely coupled.
Messages Multiple resources in a single exchange.
Documents Multiple resources bundled to support data persistence and maximum compatibility.
Services Custom support to address specific requirements that aren’t fully supported by other paradigms.


Retrieve data held in a remote system while avoiding direct coupling to remote procedures.

View Results Screen

Many web services use messages to form their own domain-specific APIs. These messages incorporate common logical commands like Create, Read (i.e. Get), Update, or Delete (CRUD). Also across the health and social care domain, we have many common entities such as Patient, Practitioner, Organisation, etc. For example, many systems will implement an API that allows you to search for Patients by their NHS Number, maybe called GetPatient, QueryPatient, CreatePatient, etc.

Rather than implementing a system specific API, we could utilise standards defined in the HTTP specification (i.e. GET, POST, etc) and standarise how we return the payload.

So rather than a wide variety of GetPatient, QueryPatient we have:

GET Request Response (server)
URI FHIR Resource
E.g. Patient
POST/PUT Request Response (server)
URI + FHIR Resource
FHIR Resource
E.g. OperationOutcome
DELETE Request Response (server)
URI FHIR Resource
E.g. OperationOutcome

This type of interface may also be called as ResourceAPI and is useful for real time applications and mobile/web based access.


  • Mobile and web application friendly, can be reused for messaging simplifying interfacing.
  • Quick to develop
  • Real Time Systems
  • Uses modern web technologies
  • Can be used with modern security and consent technologies (OAuth2, OpenID, SMART on FHIR)


  • Less suitable for large transfers of data between organisations and large systems.

Information Sharing Patterns

The following table highlights a number of information sharing patterns as described in the NHS Developer network.

tn_RegistryRepository Consider using Messaging to populate the Repository
tn_Repository Consider using Messaging to populate the Repository

NHS FHIR Examples (RESTful)


Send notifications and other information to remote systems while avoiding direct coupling to remote procedures.

View Results Screen

There are many scenarios where messaging can not be driven entirely by the consumer. This is especially true in large organisations or in scenarios where health and social care organisations need to exchange data. In these situations we need an API that recognises a set of related resources but does not tie them into specific procedures, this may also be called a MessagingAPI.

For example a Referral Request will typically contain supporting information such as a referral letter, images/scans, or other resources relevant to the referral. While the requester determines the makeup of the Referral Request and other resources, the receiving service will determine how this is handled. The requester may block (synchronous) traffic while waiting for a response but typically the response will be generated later (asynchronously).

Request (FHIR Bundle)
FHIR MessageHeader
Main FHIR Resource
(e.g. ReferralRequest)
Other FHIR Resources


  • Established and mature pattern in Health and Social Care domain
  • Process isolation, useful for communication between organisations and large systems.


  • Not suitable mobile or browser use
  • Information Governance concerns especially when used with broadcast pattern.
  • Messages need handling, this may be unnecessary for small transactions

Information Sharing Patterns

tn_RegistryRepository To store resources in the Repository
Use API to retrieve the resources
tn_Repository To store resources in the Repository
Use API to retrieve the resources
tn_StoreAndNotify To store resources in the repository
and provide Notification
Use API to retrieve the resources

NHS FHIR Examples (Messaging)###


Send documents to remote systems while avoiding direct coupling to remote procedures.

View Results Screen

A FHIR Document may be sent as the payload of a RESTful Response, Message or any Exchange Paradigm or Information Sharing Pattern. It provides a set of coherent information that is a statement of healthcare information, including clinical observations and services. A document is an immutable set of resources with a fixed presentation that can be authored and/or attested by humans, organizations and devices.

Request (FHIR Bundle)
FHIR Composition
Other FHIR Resources


  • Formatted for human readability using structured headings PRSB
  • Static coherent statement of health care at fixed point in time.
  • Can be generated on demand to provide a current statement of Patient care.


  • More complex to develop

Information Sharing Patterns

tn_StoreAndNotify To populate the repository.
Use Message or API for the notification
Use API to retrieve the document

NHS FHIR Examples (Documents)###


Execute a procedure on a remote system while avoiding direct coupling.

When providing an API, a number of operations may be available to support needs such as create, read, update, delete etc. These are widely documented in the form of POST, GET, PUT, DELETE etc. and provider and consumer are expected to understand these and simply declare which operations are supported by their API.

It is possible also possible to extend these basic interactions with a custom defined operation. HL7 describe the need to add operations as being:

  • “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.”

HL7 suggests that an operation has the following properties:

  • Each operation has a name
  • Each operation has a list of ‘in’ and ‘out’ parameters
  • Parameters are either resources, data types, or search parameters
  • Operations are subject to the same security constraints and requirements as the RESTful API
  • The URIs for the operation end-points are based on the existing RESTful API address scheme
  • Operations may make use of the existing repository of resources in their definitions
  • Operations may be performed on a specific resource, a resource type, or a whole system

Using an extended operation to support the retrieval of a predefined set of resources as discussed above, there is an inherent risk of making a provider’s API more tightly coupled to specific consumers, requiring that they have a previously agreed contract and an understanding of these specific operations. Operations designed to meet one consumer’s needs may not be appropriate for subsequent consumers.

NHS FHIR Examples (Extended Operations)###

Tags: design