RESTful API Interactions

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 and Data 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 section below 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}

Search

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

Response Handling

The HTTP status codes returned in the response aid applications in understanding whether a search was successful, and if not successful, provides some context as to why the search did not return the expected response.

These status codes are considered the base status codes that should be present in any implementing API. Implementations and guides may include additional status codes that their service supports and may supply further details on the circumstances or expected client behavior.

Please refer to FHIR R4 RESTful API and associated sections for more detail.

2xx HTTP Success

In general, if the search is properly formatted and succeeds, the API SHALL return an HTTP 200 OK status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero* or more resources in a defined order.

4xx/5xx HTTP Errors

In general, if the search fails (cannot be executed, not that there are no matches), the return value SHALL be a status code 4xx (client error) or 5xx (API/service error). An OperationOutcome SHOULD be returned detailing the error.

The error responses SHOULD use the OperationOutcome resource to return both human-readable and machine-processing information with sufficient details to enable the requester to debug the error.