Data Exchange

Unlike exchange paradigms like FHIR Documents and FHIR Messaging, which often use a subset of FHIR Resources to facilitate exchange (e.g., Bundle, DocumentReference, MessageHeader, Task), generic exchange of individual resources using RESTful APIs could apply to any and all FHIR Resources.

This guide is intended to put forward exchange requirements that can be applied across pan-Canadian specifications (with varying use cases and FHIR Resource needs). This promotes harmonization and predictability in the marketplace. Transactions defined in this guide (e.g., CA:FeX 1A) are used to convey implementable expectations, that when tested (and claimed), illuminate the eligibility for a FHIR Server and/or FHIR Client to exchange payloads defined in various pan-Canadian specifications (e.g., PS-CA).

• Setting the bar to be met by demonstrating any RESTful behavior against any FHIR Resource defined in the FHIR Base specification does little to promote this goal.

• It also does little to promote harmonization of search behaviors across interfaces, resulting in a fragmented landscape with little predictability and economies of scale for FHIR Clients/applications to depend on.

For this reason, a more nuanced approach has been applied to define conditional expectations that are Resource-specific. This approach is directly influenced and shared by IHE QEDm, IPA, and US Core.

This approach uses Capability Statements to define the mandatory interactions and the required & preferred search parameter combinations by Resource.

• This allows for interfaces that only support certain Resources (e.g., Immunization Repositories) to harmonize around exchange behaviors without incurring requirements to demonstrate support for other FHIR Resources (e.g., DiagnosticReports).

The CA:FeX Interoperability Specification contains the use cases, sequence diagrams, and requirements that complement the transactions described below.

Implementers are expected to familiarize themselves with how the following interactions are executed using the guidance outlined on the RESTful API Interactions page as well as the expectations outlined in Response Handling.

The guidance below is provided to identify how the requirements are expressed in this guide's Capability Statements.

Actors, Transactions, and Actor Options

The following diagram provides an overview of the CA:FeX Actors, Transactions and their interactions.

Single Resource Option (C)

Actors	Transaction ID	Name	Endpoint Summary	Optionality
Data Source	CA:FeX-1C	Submit Resource	/[type]	R
Data Consumer	CA:FeX-2C	Search Resource	/[type]	R
Data Consumer	CA:FeX-3C	Retrieve Resource	/[type]	R
Data Recipient	CA:FeX-1C	Submit Resource	/[type]	R
Data Responder	CA:FeX-2C	Search Resource	/[type]	R
Data Responder	CA:FeX-3C	Retrieve Resource	/[type]	R

Data Source

A Data Source submits data to a Data Recipient.

Data Consumer

A Data Consumer queries a Data Responder for data matching a set of criteria.

Data Recipient

A Data Recipient receives data from a Data Source.

Data Responder

A Data Responder returns data matching a set of criteria queried by Data Consumer.

Transaction Details

CA:FeX-1C: Submit Resource

This transaction is intended to cover simple create behavior to submit a resource to a FHIR server-assigned location. This transaction is used when the submitter expects the FHIR server to assign the submitted resource an id which can be used to retrieve the resource in the future.

Since submission of data between an external source and a recipient is not pervasively implemented (compared to search or read) - the Server CapabilityStatement acknowledges the create operation, but applies MAY conformance expectations to most of the non-Document resources.

Additional Considerations

This transaction does not further constrain or apply expectations for update as create behaviors (i.e., using PUT to supply the resource id) beyond acknowledging them as MAY support capabilities in the CapabilityStatement. This transaction does not currently cover the conditional create behavior. These are complex interactions, and it is not expected that every server will implement them.

Per the Base Specification, servers that don't support the conditional create/update/delete SHOULD return an HTTP 400 error and MAY include an OperationOutcome.

CA:FeX-2C: Search Resource

This transaction is intended to cover the search-type behavior to find FHIR Resources that meet provided search parameters. This guide enforces expectations for servers to support individual search parameters as well as some combination search parameters.

Requirements Across Resource Types

Search-type is a mandatory interaction across all resources listed in the Capability Statements with the exception of Binary and Medication resources that are typically expected to be searched for through other resources (e.g., DocumentReference, MedicationRequest).

CA:FeX requires that FHIR APIs SHALL support searches using the Patient Resource ID, with some exclusions (e.g., Medication, Binary, Practitioner, PractitionerRole).

FHIR Servers SHOULD also support chained searches based on Patient.Identifier for almost all resource types. Implementers are encouraged to provide feedback on this expectation to aid in the consideration of tightening the constraint in future releases.

CA:FeX requires that FHIR APIs that support document-oriented resources SHALL support chained searches using Patient.Identifier to search for Bundle, Composition, and/or DocumentReference.

Parameter Modifiers

In accordance with IHE QEDm, FHIR servers SHALL support the :exact parameter modifier on all query parameters of type string. This allows the FHIR Client to instruct the FHIR Server to only find and retrieve exact matches to the parameter provided (e.g., matching on whole string with casing and accents).

CA:FeX-3C: Retrieve Resource

This transaction is intended to cover read behavior to retrieve a resource using its resource id. This transaction is typically used when the requester knows the server-assigned location of the resource it is retrieving. This could be because the system stored the resource id from a previous interaction (e.g., submission or search results), or because the system wants to retrieve the additional information from resources that were referenced but not included in search results (e.g., a Practitioner or an Encounter resource referenced by an Observation), etc.

The Server CapabilityStatement of this guide enforces the expectation that read is mandatory on any FHIR resource type that a conforming FHIR Server claims to support.

Additional Considerations

This transaction does not further constrain or apply expectations for reading a specific version of a resource or retrieving the full history of versions for a resource beyond acknowledging them as MAY support capabilities in the CapabilityStatement. These expectations may be evaluated for stricter expectations in future releases.

Notes

Querying for a FHIR Server's CapabilityStatement is a fundamental step in understanding what behaviors and resources a FHIR Server supports. Should a Client search for a resource that the FHIR Server does not support, the FHIR Server SHALL return an OperationOutcome.issue.code valued as: ‘not-supported’ and an operationoutcome.issue.details valued as: MSG_NO_MATCH No Resource found matching the query "%s". This is in alignment with IHE QEDm requirements; however implementers are encouraged to provide feedback on this requirement.