Skip to main content
Previous sectionNext section

Introduction

The InterSystems IRIS FHIR Accelerator Service (FHIRaaS) is a reliable, secure, low maintenance solution that your healthcare application can use to store and retrieve FHIR® data, allowing you to leverage powerful FHIR technology from InterSystems without worrying about setting up its infrastructure.

To take a deep dive into the FHIR support of FHIRaaS without needing to parse through its Capability Statement, see Supported Interactions and Operations. If you are new to FHIR and FHIR servers, you can use the Quick Start to use RESTful API requests to store and retrieve FHIR data with little to no prior experience.

The preview of FHIRaaS gives you the opportunity to explore all of its potential without having to wait for the official commercial launch. Being a preview, there are a number of known limitations and incomplete functionality that will be addressed before the commercial release. For a complete list, see Known Issues in Preview.

Quick Start

Once you have deployed the InterSystems IRIS FHIR Accelerator Service (FHIRaaS), you can take the following tour to familiarize yourself with FHIR resources and begin making RESTful FHIR requests.

Find your base URL

FHIRaaS has a unique URL that serves as the base of the RESTful FHIR requests made to the service. This is the base URL of each endpoint that you use to work with FHIR data. For example, the request to retrieve a particular patient might be GET https://myBaseURL/Patient/10 while a request that stored an Observation might be POST https://myBaseURL/Observation.

Just navigate to the FHIR tab to find the base URL of your FHIRaaS. For example, the base URL of your service might look like:

https://z4xyins06h.execute-api.us-east-2.amazonaws.com/fhir
Obtain an API Key

All requests to FHIRaaS must be authenticated, whether it be with an API key or through OAuth 2.0. For the purposes of this Quick Start, you will use an API key to authenticate the requests.

The User Management tab allows you to add multiple users who can access the FHIRaaS. Each user is given a unique API key when their account is created. For security, this key cannot be accessed again once the dialog is dismissed, so make sure it is copied to a safe place! To generate a new key, you will need to create a new user.

Explore the Development Portal

The Development Portal found on the API Development tab is a great way to familiarize yourself with FHIR resources and make basic API requests that store and retrieve these resources from FHIRaaS.

Learn about the Patient Resource

The Development Portal allows you to learn more about individual R4 resources, which is particularly useful if you are new to FHIR.

  1. From the Choose FHIR Resource drop-down, select Patient. When you are done with the Quick Start, you can use this drop-down to learn about other resources.

  2. Next, expand the POST /Patient section of the Development Portal.

  3. From here, you can learn more about the structure of a R4 Patient resource by looking at sample Patients. The Example Value text box uses JSON to display the Patient sample that is currently selected in the Examples drop-down.

  4. You can also view the schema of a Patient resource. Simply select Schema to explore the data types, descriptions, and hierarchy of the fields of a valid R4 Patient resource. To see how a Patient is described in the official FHIR specification, see Resource Patient - Content.

Authenticate your FHIR Requests

Like all requests to FHIRaaS, the requests made through the Development Portal must be properly authenticated. To authenticate your requests made through the Development Portal:

  1. Near the top of the API Development tab, select Authorize.

  2. In the Value field of the apiKey section, paste the API key that was displayed when you created the user on the User Management tab.

  3. Select Authorize.

  4. Select Close.

Add a Patient

You can use the Development Portal to add Patient resources to FHIRaaS without needing to know the syntax of the FHIR request. In FHIR development, adding a resource is accomplished with the create interaction. To add a Patient to the service:

  1. Expand the POST /Patient section.

  2. Select Try It Out.

  3. Ensure that patient-example-a.json is selected in the Examples drop-down. Notice that the value of the Patient’s gender field is male.

  4. Select Execute.

You can review the cURL call that was executed, which gives you an idea of the FHIR request your application would make to add a Patient.

Search for Patients

Just as you can use the POST /Patient endpoint to add a Patient to FHIRaaS, the Development Portal allows you to use a GET /Patient endpoint to retrieve Patient resources from the service. Executing a request to this endpoint without specifying parameters will retrieve all of the Patient resources, including the one you just added. However, in this Quick Start, you will retrieve only male patients.

  1. Expand the GET /Patient section.

  2. Select Try It Out.

  3. Scroll through the parameter fields until you find gender, which is a standard search parameter for Patient resources.

  4. Enter male.

  5. Scroll down and select Execute.

You can review the cURL call that was executed, which gives you an idea of the FHIR request your application would make to retrieve a Patient using one or more search parameters. Notice that gender=male is added to the end of the endpoint as a query parameter.

The Response Body displays a FHIR bundle that contains all of the male Patients in your FHIRaaS. You can download this JSON bundle to make it easier to inspect its contents, including finding the Patient that you added during this Quick Start.

Use a REST Client

When using Postman, Advanced REST Client, or any other REST client, be sure to authenticate each request by specifying your API Key as the value of the x-api-key header parameter. For example, your request could include x-api-key: 80nlTZOMyAPIKey. Of course, if FHIRaaS is secured with OAuth 2.0, you can use a token to authenticate your requests.

While the API Development tab is a great way to start exploring the capabilities of FHIRaaS, if you want to try out more complex queries that leverage all of the available search parameters, you need to use a REST client. For a complete list of the standard search parameters, modifiers, and prefixes that are available with FHIRaaS, see Search Interaction. These parameters, modifiers, and prefixes can be applied to all searches.

Of course, you can mix these common search parameters with resource-specific parameters when performing a query. As you have seen in this Quick Start, the API Development tab lists all of the resource-specific parameters that are available when searching for resources. These resource-specific parameters are also summarized in the official FHIR specification; for example, you can review the Patient-specific search parameters.

Authentication and Authorization

FHIR requests that are made to the FHIRaaS can be authenticated with API keys or through OAuth 2.0.

API Key Credentials

The User Management tab allows you to obtain API keys that can be used to authenticate FHIR requests to FHIRaaS. Each new user is assigned a unique API key that must be copied to a safe location; once you dismiss the dialog with the key, it cannot be retrieved.

FHIR requests to FHIRaaS are authenticated by including the API key in the header of the request. Simply include the key as the value of the x-api-key header.

OAuth 2.0

The OAuth 2.0 functionality of FHIRaaS is under active development.

Uploading Data

You can use the instructions on the Data Management tab to upload FHIR bundles from your local machine. The service provides a private key for SFTP file transfer. Using this key, you can connect to SFTP and transfer bundles stored in JSON format.

One common issue users encounter is an error message from AWS stating “Permission 0644 are too open for use with the private key.” In this case, the private key that you downloaded is ignored. An easy fix requires using a terminal command to chmod 400 the private key file.

The SFTP remote directory is FHIR. You must use this directory. When all of your bundles have been uploaded (as indicated by the count of bundles), select Import. To view the progress of the import, select the Refresh button. After the bundles are uploaded to the FHIR server, they are no longer visible in directory.

Access Logs

The Access Logs tab provides valuable information on who is using your service, and what FHIR requests they are making. These logs show when the FHIR request was made, from what IP address, and the status of the response.