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¶m2=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.
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.
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.
File Operations
In order to upload or download a file, a temporary URL should be requested. These custom operations are not part of the HL7 FHIR standard. See below the pertaining URLs, error messages:
Request URL for file upload
POST the file name using this format
{“fileName":"file123.docx"} to http://api.otn.ca/hub/v2/documents/
If this operation is successful, a response similar to following is returned:
{ "url":" http://api.otn.ca/hub/v2/files/XcLBv57ifQGt_vB4YkYJfX5CNtW1Ozm7UzawNs-r5WF", "expiresInMin":xyz }
If this operation fails an error form table below is returned :
| Description | Code | HTTP Code |
|---|---|---|
| User not found in eConsult | R_USER_NOT_FOUND | 404 |
| User doesn't have proper permission to invoke this API | R_USER_INSUFFICIENT_PERMISSIONS | 403 |
| Mandatory field missing | R_MANDATORY_FIELD_MISSING | 400 |
| Internal error | R_INTERNAL_ERROR | 500 |
ERROR example:
{ "status":403, "app":"FILES", "error":"R_MANDATORY_FIELD_MISSING", "reference":"R-8a32fcd3-03d2-42a0-90f4-1c28cdfc7c79", "details":"File type is not supported", }
Upload File
Using temporary URL retreived in the previous step, a file may be uploaded as follows:
POST http://api.otn.ca/hub/v2/files/XcLBv57ifQGt_vB4YkYJfX5CNtW1Ozm7UzawNs-r5WF file123.docx
Response example of a successful operation:
{ "id":24192867, "fileName":" file123.docx ", "contentType":"application/vnd.openxmlformats-officedocument.wordprocessingml.document", "createdBy":"username", "fileSize":12784 }
If the above operation fails on of the error message in the table below is returned:
| Description | Code | HTTP Code |
|---|---|---|
| Non-supported file types | R_FILE_TYPE_NOT_SUPPORTED | 400 |
| File size exceeds 500MB | R_FILE_SIZE_TOO_LARGE | 400 |
| Virus detected | R_VIRUS_DETECTED | 400 |
| File upload URL expired. The expiration period is 30 seconds | R_EXPIRED_FILE_URL | 400 |
| File content is missing or file size is 0 | R_EMPTY_FILE | 400 |
| The uploaded file name does not match the record | R_INVALID_FILE_NAME | 400 |
| The URL is invalid | R_INVALID_URL | 400 |
| Non-supported file types | R_FILE_TYPE_NOT_SUPPORTED | 400 |
| Internal error | R_INTERNAL_ERROR | 500 |
ERROR example:
{ "status":403, "app":"FILES", "error":"R_EXPIRED_FILE_URL", "reference":"R-8a32fcd3-03d2-42a0-90f4-1c28cdfc7c79", "details":"File upload URL expired. The expiration period is 30 seconds. }
Request URL for file download
GET http://api.otn.ca/hub/v2/documents/24192867where 24192867 is file ID from the previous step. See below a Sucessful response example:
{ "url": " http://api.otn.ca/hub/v2/files/XcLBv57ifQGDILHY8VHo214t_X", "expiresInMin": 15 }
Table below lists possible error codes of the above operation should it fail:
| Description | Code | HTTP Code |
|---|---|---|
| User not found in eConsult | R_USER_NOT_FOUND | 404 |
| User doesn't have proper permission to invoke this API | R_USER_INSUFFICIENT_PERMISSIONS | 403 |
| File ID missing | R_MANDATORY_FIELD_MISSING | 400 |
| File not found | R_FILE_NOT_FOUND | 404 |
| Internal error | R_INTERNAL_ERROR | 500 |
Download file
GET http://api.otn.ca/hub/v2/files/ XcLBv57ifQGDILHY8VHo214t_X
Response will be the file streamed.If this operation fails, one of the error message in the table below will be returned:
| Description | Code | HTTP Code |
|---|---|---|
| PracticeID doesn't have proper permission to invoke this API | R_PRACTICE_ID_INSUFFICIENT_PERMISSION | 403 for future use only, not returned in POC |
| User not found in eConsult | R_USER_NOT_FOUND | 404 |
| User doesn't have proper permission to invoke this API | R_USER_INSUFFICIENT_PERMISSIONS | 403 |
| The URL is invalid | R_INVALID_URL | 400 |
| File not found | R_FILE_NOT_FOUND | 404 |
| File upload URL expired. The expiration period is 30 seconds | R_EXPIRED_FILE_URL | 400 |
| Internal error | R_INTERNAL_ERROR | 500 |