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 1) 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).
CA:FeX Transactions
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.
Submit Data
This capability 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.
HTTP Operations
This capability can be leveraged using HTTP POST request. Implementers are expected to familiarize themselves with how create interactions are executed using the FHIR RESTful API framework.
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.
Search for Data
This capability 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).
HTTP Operations
This capability can be leveraged using HTTP GET or POST request. Implementers are expected to familiarize themselves with how search-type interactions are executed using the FHIR RESTful API framework.
Per the FHIR standard on HTTP search interaction:
- Because of the way that some user agents and proxies treat
GETandPOSTrequests, in addition to theGETbased search method, servers that support search SHALL also support aPOSTbased search - Supporting
GETmeans that PHI (Personal health information) might appear in search parameters, and therefore in HTTP logs. For this reason logs should be regarded as being as sensitive as the resources themselves. This is a general requirement irrespective of the use ofGET- see the FHIR Security page for further commentary. - If the search succeeds, the server SHALL return a 200 OK HTTP 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.
- If the search fails (cannot be executed, not that there are no matches), the return value SHALL be a status code 4xx or 5xx with an OperationOutcome. See Response Handling.
Additional Considerations
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.
Retrieve Data
This capability 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.
HTTP Operations
This capability can be leveraged using HTTP GET request. Implementers are expected to familiarize themselves with how read interactions are executed using the FHIR RESTful API framework.
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.