RESTful API Interactions

This IG page includes summarized RESTful API interactions derived from the base FHIR specification. In the event of any discrepancies or conflicts between the interactions summarized here and the base specification, the base specification shall prevail. Users are encouraged to refer to the base FHIR specification for detailed and complete guidance.

A RESTful API is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. FHIR provides various APIs for different types of transactions with the resources.

RESTful APIs use a standard convention for describing the format of the interaction:

VERB [base]/[type]/[id] {?_format=[mime-type]}

  • The first word is the HTTP verb used for the interaction (e.g., GET, PUT, DELETE)
  • Depending on the type of interaction, there are different rules for what content is mandatory and what is considered optional
    • Content surrounded by [] is mandatory, and will be replaced by the string literal identified.
    • Content surrounded by { } is optional
    • Some insertion values include:
      • base: The Service Base URL (e.g., “https://fhir-server.com”)
      • mime-type: The Mime Type (e.g., application/fhir+json)
      • type: The name of a resource type (e.g., "Patient")
      • id: The Logical Id of a resource (e.g., “24342”)
      • vid: The Version Id of a resource (e.g., "1.1")
      • compartment: The name of a compartment for finding a fixed set of related resources (e.g., "GET [base]/Patient/[id]/Communication")
      • parameters: URL parameters as defined for the particular interaction (e.g., ”_format", "_summary")

RESTful API Interaction Expectations

This guide defines a set of resources, RESTful interactions, search parameters, and FHIR Operations that servers in Canada are expected to support to be conformant to the CA:FeX Server CapabilityStatement.

The CA:FeX Server CapabilityStatement covers the RESTful API expectations to engage in the Single Resource Exchange, Multiple Resource Exchange, and Exchange using Operations described in Document Exchange.

Given that the use of FHIR in Canadian health information exchange is still nascent, this release focuses its constraints on the more foundational capabilities that FHIR implementers typically start with.

Search and Read interactions are considered mandatory across the majority of nominated resource types.

  • The search and retrieval of existing resources using FHIR APIs provides a high degree of value to early implementers and these interactions are consistently relevant across health information exchange use cases.

Other RESTful interactions (e.g., create, update, patch, delete, history, vread) are considered preferred or optional across nominated resource types.

  • Create, update, patch, and delete interactions involve the modification of data that exists on a FHIR server. While these types of interactions are more likely to be used in internal operations or event-driven use case cases, they typically necessitate stricter rules between exchange partners that are more commonly enforced through use case implementation guides or individual implementation details.
  • History and vread interactions involve the retrieval of details regarding the change history of a resource or set of resources. These are typically used in a subset of use cases where the repeated updating of a resource is expected in a given workflow. While powerful, these interactions may not be prioritized equally in early implementer environments.

Regardless of the degree in which they are enforced in this guide, implementers should familiarize themselves with the full set of details regarding FHIR RESTful API use and syntax provided in the FHIR Base Specification.

Summarized details on interaction and response syntax are provided in the Response Handling to provide preliminary context behind the API interactions that implementers are expected to support.

Note: Details on the interactions that a server supports can be found within the CapabilityStatement that the requester retrieves as a pre-requisite step to interaction. However, it is not required to be conducted at the beginning of every session to avoid forcing performance costs on clients that interact with known servers that do not update their security services and/or supported capabilities frequently.

Interaction Specific Syntax

Read

The Read interaction allows for the return of a single instance of the requested resource using the resource id.

GET [base]/[type]/[id] {parameters}

The Search interaction allows for resources to be searched for using filter criteria.

The FHIR RESTful Search API requires that servers that support search SHALL support both HTTP GET and HTTP POST searches.

Clients can choose to execute searches using either GET or POST. However, some systems may prefer the use of POST to avoid concerns with PHI (Personal health information) appearing in search parameters (and subsequently in HTTP logs).

These are formatted as follows:

GET [base]/[type]?name=value&…

POST [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}

For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL or as an application/x-www-form-urlencoded submission for a POST:

Create

The Create interaction allows for a resource to be created in a server-assigned location by performing a POST operation in the RESTful framework:

POST [base]/[type]{?_format=[mime-type]}

Update

The Update interaction allows for an existing resource to be updated to include new information, or for the creation of a resource if no resource already exists in the provided resource id.

PUT [base]/[type]/[id]

Patch

The Patch interaction is an alternative method of updating an existing resource. Patch allows for only the changed data to be supplied as opposed to the entire resource (reducing the bandwidth needed for the request).

PATCH [base]/[type]/[id] {?_format=[mime-type]}

Delete

The Delete interaction is used to remove a resource from the FHIR Server with the HTTP DELETE verb:

DELETE [base]/[type]/[id]

History

The History interaction allows for the retrieval of the history of either: a nominated resource (history-instance), all resources of a given type (history-type), or all resources supported by the system (history-all). These are performed using the HTTP GET verb:

GET [base]/[type]/[id]/_history{?[parameters]&_format=[mime-type]}

GET [base]/[type]/_history{?[parameters]&_format=[mime-type]}

GET [base]/_history{?[parameters]&_format=[mime-type]}

The returned Bundle includes the resources and/or logged details (e.g., details regarding the update or delete interaction, lastModified date)

Vread

The Vread interaction allows for a version specific resource to be read/retrieved. Resources that have a meta.versionId specified can be read this way using the HTTP GET verb:

GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}

The use of vread is predicated on knowing the version id (e.g., through history interaction, or recording the version id returned in a previous read or search).