Technical Specifications > RESTful FHIR API


Specification - RESTful FHIR API

This section of the implementation guide defines specific requirements for systems wishing to conform to the RESTful FHIR API requirements in this implementation guide (IG). The focus is on the expected use of FHIR's RESTful API to support the exchange of information with a Referral Management System (RMS).

The requirements and expectations described here are not intended to be exhaustive. This IG establishes a baseline of expected behavior that communication partners can rely on and then build upon without standardizing referral pathways or defining what clinical data must be exchanged when referring patients. Therefore, implementers SHALL anticipate the need to discuss and mutually agree on the approach that will be used to support the different referral pathways, forms used, required supporting information (etc.) that will be enabled through the implementation of the RESTful API.

Future iterations of this IG are expected to build upon this baseline.

Context

Prerequisites

Before reading this formal specification, implementers are encouraged to first familiarize themselves with other key portions of this IG, specifically:

  • The Business Model for information about what this IG aims to accomplish including an overview of the business solution and process flow this specification will enable.

  • The Technical Background page for information about the underlying specifications this IG builds upon including references to sections that implementers should read to establish a necessary foundation to understand the constraints and usage guidance described here.

Participating Systems

The RESTful FHIR API provides implementers of eServices solutions with a standard way to expose or interact with information that resides in a Referral Management System (RMS), HealthcareService Directory (HSD) or Point of Service System using HTTP requests/responses.

Two different software applications participate in a RESTful integration. In an eServices context these are typically:

  • A RESTful Server is a POS, RMS, or HSD application that provides authorized users of other systems with access to information needed to create a request or to check on the status of an existing request; and
  • A RESTful Client is an RMS application that has been configured to allow the query and retrieval of information from a RESTful server.

Introduction to FHIR RESTful Operations

FHIR is described as a 'RESTful' Specification supporting Level 2 of the REST Maturity model. "RESTful FHIR" is an exchange framework defined within the FHIR specification. Transactions are performed directly on the server resource using an HTTP request/response. The API describes the FHIR resources as a set of operations (known as "interactions") on resources where individual resource instances are managed in collections by their type. Servers can choose which of these interactions are made available and which resource types they support. RESTful Servers conforming to this specification SHALL provide a Capability Statement that specifies which interactions and resources are supported.

To support business workflows, RESTful interactions are used to exchange information between a healthcare service provider or delegate and a system containing a directory of healthcare services, providers, and existing requests.

The interactions supported within this guide are Search and Read.

Where search operations will span across a set of resources based on parameters supplied within a search operation, the read interaction will access the contents of a resource through an HTTP GET command.

Please refer to the FHIR RESTful API for more information on HL7 FHIR RESTful API.

Searching

This section provides a basic introduction to FHIR search. For full details please review the official documentation for FHIR search.

Searching for resources is fundamental to the mechanics of FHIR. Search operations traverse through an existing set of resources filtering by parameters supplied to the search operation.

In the simplest case, a search is executed by performing a GET operation in the RESTful framework:

GET [base]/[type]?name=value&...{&_format=[mime-type]}}

This searches all resources of a particular type using the criteria represented in the parameters.

Because of the way that some user agents and proxies treat GET and POST requests, in addition to the get based search method above, servers that support search SHALL also support a POST based search:

POST [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}
Content-Type: application/x-www-form-urlencoded
param1=value&param2=value

This has exactly the same semantics as the equivalent GET command. Note that in the POST variant, parameters may appear in both the URL and the body. Parameters have the same meaning in either place. Since parameters can repeat, putting them in both places is the same as repeating them (which is valid for some parameters and not for others).

Note: Supporting GET means 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 of GET.

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.

Search operations are executed in one of three defined contexts that control which set of resources are being searched:

  • A specified resource type: GET [base]/[type]?parameter(s)
  • A specified compartment, perhaps with a specified resource type in that compartment: GET [base]/Patient/[id]/[type]?parameter(s)
  • All resource types: GET [base]?parameter(s) (parameters common to all types). If the _type parameter is included, all other search parameters SHALL be common to all provided types. If _type is not included, all parameters SHALL be common to all resource types.

The response to any search operation is always a list of resources in a Bundle.

Standard Search and Result Parameters

Search and Result parameters used within this implementation guide can be found in the Search Parameters section of the StructureDefinition pages. Additional information on search and result parameters can be found the HL7 FHIR Search page.

The following table provides a summary of the search parameters used within this implementation guide. Please refer to the Search Parameters section at the bottom of each Structure Defition page to see which parameter is applicable.

Query Search Parameter Description
_id This parameter refers to the logical id of the resource.
_lastUpdated This parameter can be used to select resources based on the last time they were changed.
_text This parameter is used to search on the narrative of the resource.
_content This parameter is used to search on the entire content of the resource.

Search Result Parameters

Search Result Parameter Description
_sort The sort parameter is used to indicate the order in which to return search results.
_count The count parameter returns the results of search in a series of pages. This parameter instructs the server on how many resources are to be returned in a single page.
_include This parameter retrieves the primary resource and resources that are referenced by the primary resource.
_revinclude This parameter retrieves resources that reference the primary resource.
_summary This parameter returns a portion of the resource.

RESTful Interactions

The sequence diagram below illustrates business events that may be supported in eReferral and eConsult integrations as well as information exchanged between the RESTful Client and RESTful Server.

# Trigger Event Search Resource Resource Search Parameters Sample Request
1 Searching existing service request(s). These search(es) allow client systems to view information on existing request(s such as status, requesters, and recipients. ServiceRequest ServiceRequest Search Parameters GET [BASE]/ServiceRequest?patient=9561357 or GET [BASE]/ServiceRequest?_id=123
Refer to the ServiceRequest supported search parameters
2 Bulk Export - Client requests export of an entire service directory from server. This enables service directories to be made available locally. HealthcareService HealthcareService Search Parameters GET [BASE]/$export?_type=HealthcareService
2b Client received an update to the service directory HealthcareService HealthcareService Search Parameters GET[BASE]/HealthcareService/$everything
3 Bulk Export - Client requests export of service directory changes that occurred after a specified date. May be used to keep service directories up-to-date. HealthcareService HealthcareService Search Parameters GET [BASE]/$export?_type=HealthcareService&_since=2022-03-15T11:00:00.000-04:00
4 Searching for a single HealthcareService. HealthcareService HealthcareService Search Parameters GET [BASE]/HealthcareService?identifier=49383574

Note: If the identifier uses a system that is not a GUID, then the GET can be performed on ?identifier=[system]|[code]

ServiceRequest

Searches on ServiceRequest are performed to query, retrieve and view existing requests. Returned bundles MAY include Patient, PractitionerRole, Practitioner, Organization, Location, QuestionnaireResponse, Questionnaire, Condition, AllergyIntolerance, Consent, DocumentReference and HealthcareService resources.

Workflow Example

A provider may wish to view active referral requests submitted for a patient. The bundle returned will include ServiceRequest, and Patient resources. The outcome of the search on ServiceRequest may result in the creation of a new request, or an update performed on an existing request. In either scenario, the Direct Messaging section of this implementation guide will provide further details on the message types supported to complement the action.

Sample Search String:

GET [BASE]/ServiceRequest?status=active&patient=3640897&_include=ServiceRequest:patient

Supported search parameters on ServiceRequest can be found on the Structure Definition page.

HealthcareService

Bulk Export Queries allow client systems to extract and retrieve service directories from servers. Access to a service directory enables an RMS Source to view available services and select potential recipients of a request. Clients also have the ability to ensure their service directories are up-to-date by requesting updates based on date.

Workflow Example

Prior to creating and/or submitting a request, a search is performed to determine the recipient of a request. The bulk import of the service directory makes the data available for a requester to determine the recipient of a request.

Supported search parameters on HealthcareService can be found on the Structure Defintion page.