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 (further described here):

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

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.

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

The RESTful interactions that are the focus of this guide are described below. For a comprehensive information see the HL7 FHIR RESTful API specifications:

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.

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

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

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]}