Skip to main content

Introduction to InterSystems FHIR Server

InterSystems® FHIR® Server 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.

If you want to use FHIR Server, you can sign up for a subscription or a free 30-day trial. Follow the easy steps in this introduction to get up and running.

Once you have created a FHIR Server deployment, you can use the Guided Tour to learn how to use RESTful API requests to store and retrieve FHIR data with little to no prior experience.

Before creating an application that uses FHIR Server, you need to choose an Authentication and Authorization strategy, using API keys or OAuth 2.0. Then you will need to Set Up Access Controls.

For information on the day-to-day management of FHIR Server, see InterSystems FHIR Server Reference Information.

To take a deep dive into the FHIR support provided by FHIR Server without needing to examine its Capability Statement, see Supported Interactions and Operations.

To learn how a development team can work together using FHIR Server, see Tenants PageOpens in a new tab.

If you encounter any difficulties while using FHIR Server, see InterSystems FHIR Server Known Issues.

Log in to the Cloud Services Portal

The InterSystems Cloud Services Portal allows you to manage FHIR Server and any additional InterSystems cloud services.

If you have an account in the Cloud Services PortalOpens in a new tab, log in to the portal.

If you do not have an account, sign up for one, as follows:

  1. In your browser, go to the Cloud Services Portal login pageOpens in a new tab, and click Create New Account.

  2. On the Create Your Account page, enter the requested information, and click Create Account.

  3. Type the verification code sent to the email account you provided, and click Confirm Account.

After you create your new account, you are taken to the Cloud Services page.

Sign Up for FHIR Server

You can create a FHIR Server subscription or start a free 30-day trial from the Cloud Services page of the Cloud Services Portal.

Create a Subscription

You can subscribe to FHIR Server whether you are a new FHIR Server customer or are currently signed up for a trial.

To subscribe to FHIR Server:

  1. In Cloud Services Portal, on the main menu, click Cloud Services.

    The Cloud Services page shows you any active subscriptions you have to InterSystems cloud services and allows you to sign up for additional services.

  2. On the FHIR Server card, click Subscribe.

  3. On the Subscribe page, read the pricing information and subscription options, and then Subscribe using the method of your choice.

    If you subscribe to FHIR Server with InterSystems, we will bill you directly. If you subscribe with your current cloud provider, billing and subscription management are handled through your account with that cloud provider.

You can also subscribe to FHIR Server and other InterSystems cloud services directly from the AWS MarketplaceOpens in a new tab.

When you subscribe to FHIR Server, the subscription is tied to your Cloud Services Portal account and your default tenantOpens in a new tab.

If you are not ready to commit to a subscription, you can try FHIR Server for free.

Start a Free 30-Day Trial

If you want to explore the features of FHIR Server without charge, you can start a free 30-day trial.

To start a trial:

  1. In Cloud Services Portal, on the main menu, click Cloud Services.

    The Cloud Services page shows you any active subscriptions you have to InterSystems cloud services and allows you to sign up for additional services.

  2. On the FHIR Server card, click Start Trial.

  3. On the Subscribe page, read the information on the screen, and then click Start Trial.

    If you see multiple tenantsOpens in a new tab listed, select the tenant in which you would like to start the trial. If you are a new user, you will see only your default tenant.

Note that some capabilities of FHIR Server (such as High Availability, horizontal scaling, or multiple deployments) are not permitted for trial users.

When you are satisfied that FHIR Server meets your needs, create a subscription before the trial expires to unlock the full capabilities of the service. Your deployment will begin to accrue charges at that time.

Create a Deployment

Once you have signed up for FHIR Server, you are ready to deploy it in the cloud. If you are a subscriber, you can create multiple deployments, for example, development, test, and live. If you are trial user, you are limited to a single deployment.

Note:

If you have just subscribed to FHIR Server in the AWS Marketplace, you may need to wait a few minutes for the subscription to be finalized. You can check to see if this has occurred by checking the Cloud Services page in the Cloud Services Portal and seeing if FHIR Server is listed under Active Subscriptions.

  1. In the Cloud Services Portal, on the main menu, click Deployments.

  2. On the Deployments page, click Create New Deployment.

  3. On the Create InterSystems Deployment page, in the Deployment Options section:

    1. Under InterSystems Services, select FHIR Server.

    2. Under Deployment Size, select a size.

      A description of the typical use case is listed for each size. (“Extra Small” is the only size available to trial users.)

    3. Optionally, select the Highly Available (HA) Configuration to deploy a mirrored backup server automatically to minimize or eliminate downtime to FHIR Server. (Not available for trial users.)

      Note:

      Selecting this option will result in a higher cost to your subscription. This feature cannot be enabled or disabled after the deployment is created.

    4. Click Continue.

  4. In the Cloud Options section:

    1. Under Cloud Provider, select a provider. (“Amazon Web Services” is the only provider currently available.)

    2. Under Region, select a region.

    3. Click Continue.

  5. In the Deployment Name section:

    1. Type a name for your deployment. This cannot be changed once created.

    2. Click Continue.

  6. In the Review section:

    1. Review the summary information.

    2. Click Create.

It takes a few minutes to deploy FHIR Server. When the deployment has completed, the status under the deployment name changes to RUNNING.

Click the card for the deployment to go to the Overview page for your new deployment. This page contains summary information, including your deployment's expiration date, API Key and OAuth 2.0 endpoints, and Deployment ID. The Deployment ID uniquely identifies your deployment. To save on the consumption of cloud resources, you can temporarily stop a deployment from the Overview page if you are not actively using it. For more information, see Overview Page.

Other actions are available by clicking the action menu at the top right of the card, such as setting the Service Level for the deployment or deleting the deployment. For more information, see Deployments pageOpens in a new tab.

Trial users are limited to one deployment.

Guided Tour

Once you have deployed FHIR Server, you can take the following tour to familiarize yourself with FHIR® resources and begin making RESTful FHIR requests.

Find Your FHIR Endpoint

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

Just navigate to the Overview page to find the FHIR endpoint of your FHIR Server. For example, the FHIR endpoint might look like:

https://fhir.yaetvlxv.static-test-account.isccloud.io

Obtain an API Key

All requests to FHIR Server must be authorized, whether it be with an API key or through OAuth 2.0. For the purposes of this Guided Tour, you will use an API key to authorize the requests.

The Credentials page allows you to add an API key for each user who can access FHIR Server. Create an API key now to use for this tour. For security reasons, this key cannot be accessed again once the dialog is dismissed, so make sure to copy it to a safe place! For more information on creating an API Key, see API Keys.

Shortcut: If you are familiar with FHIR requests and like to use a REST client like Postman, you now have all the information you need to start interacting with FHIR Server. Use the FHIR endpoint as the base URL of your FHIR requests, and authorize those requests by putting your API key in the x-api-key header. However, if you are new to FHIR or RESTful APIs, you can continue with this Guided Tour by using FHIR Server Developer Portal.

Explore the Developer Portal

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

FHIR Server comes preloaded with synthetic healthcare data so that you can get started right away, without having to generate your own test data or de-identify existing data.

Learn About the Patient Resource

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

  1. From the Select Resource drop-down list, select Patient.

    When you are done with the Guided Tour, you can use this drop-down list to learn about other resources.

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

  3. From here, you can learn more about the structure of a FHIR 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 list.

  4. Look at the Schemas section of the page to explore the data types, descriptions, and hierarchy of the fields of a valid FHIR R4 Patient resource.

    To see how a Patient is described in the official FHIR specification, see Resource Patient - ContentOpens in a new tab.

Authorize Your FHIR Requests

Like all requests to FHIR Server, the requests made through the Developer Portal must be properly authorized. To authorize your requests made through the Developer Portal:

  1. Near the top of the API Development page, click Authorize.

  2. On the Available Authorizations dialog box, in the Value field, paste the API key you created on the Credentials page.

  3. Click Authorize.

  4. Click Close.

When you are done using the API Development page, click the Authorize button again, and then click Logout.

Add a Patient

You can use the Developer Portal to add Patient resources to FHIR Server without needing to know the syntax of the FHIR request. In FHIR development, adding a resource is accomplished with the createOpens in a new tab interaction. To add a Patient to the service:

  1. Expand the POST /Patient section.

  2. Click Try It Out.

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

  4. Click 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 FHIR Server, the Developer 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 Guided Tour, you will retrieve only male patients.

  1. Expand the GET /Patient section.

  2. Click Try It Out.

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

  4. Type male.

  5. Scroll down and click 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 bundleOpens in a new tab that contains all of the male Patients in your FHIR Server. You can download this JSON bundle to make it easier to inspect its contents, including finding the Patient that you added during this Guided Tour.

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 FHIR Server is secured with OAuth 2.0, you can use a token to authenticate your requests.

While the API Development page is a great way to start exploring the capabilities of FHIR Server, 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 FHIR Server, 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 Guided Tour, the API Development page 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 parametersOpens in a new tab.

Authentication and Authorization

FHIR® requests that are made to FHIR Server can be authenticated by API Key or OAuth 2.0/OpenID Connect using an identity provider (IdP).

API Key Credentials

API keys can be used to authenticate FHIR requests to FHIR Server. Each user is assigned a unique API key that is sent in the header of the request to allow access to the service, as shown in the following example.

curl -i -X POST "https://fhir.c1zncw08fpyg.static-test-account.isccloud.io/Patient" 
-H "x-api-key:<YOUR-API-KEY>" -H "accept: application/fhir+json" -H "Content-Type: application/fhir+json" 
-i -d "{ \"name\": [ { \"use\": \"official\", \"family\": \"Johnson\", \"given\": [ \"Darcy\" ] } ], 
\"gender\": \"female\", \"birthDate\": \"1970-02-02\", \"resourceType\": \"Patient\" }"

OAuth 2.0/OpenID Connect

FHIR Server OAuth solution is centered around having an authentication server that manages your organization's users and applications. During development, if you want a simplified way to send OAuth tokens to FHIR Server from an application, you can use FHIR Server integrated authentication server. However, an enterprise-grade solution that leverages OAuth and OpenID Connect will most likely use an authentication server that uses an external, third party IdP. In such an implementation, authentication (OpenID Connect) and authorization (OAuth 2.0) for your application is handled by your IdP, not FHIR Server. FHIR Server simply enforces the OAuth tokens obtained from the IdP when responding to FHIR requests from the application.

In many cases, your organization's IdP will already include the users who will be accessing the application that connects to FHIR Server. For example, members of a health insurance company who use applications built for the organization will likely already be users in an IdP. In this scenario, you will simply register your new application with the IdP and give the existing users permissions to access the application. In FHIR Server, you configure your IdP as an authentication server. Then you configure the application to use that authentication server.

When using OAuth 2.0, the user is assigned a temporary token that is sent in the header of the request to allow access to the service, as shown in the following example.

curl -i -X POST "https://fhirauth.c1zncw08fpyg.static-test-account.isccloud.io/oauth2/Patient" 
-H "Authorization: Bearer <YOUR-TOKEN>" -H "accept: application/fhir+json" -H "Content-Type: application/fhir+json" 
-i -d "{ \"name\": [ { \"use\": \"official\", \"family\": \"Johnson\", \"given\": [ \"Darcy\" ] } ], 
\"gender\": \"female\", \"birthDate\": \"1970-02-02\", \"resourceType\": \"Patient\" }"

Roles and Responsibilities

Keeping patient data, including Protected Health Information (PHI), safe and secure is of utmost importance in a healthcare application. FHIR Server is designed to use OAuth to protect PHI by inspecting access tokens that accompany FHIR requests from the application. FHIR Server will reject any request that tries to exceed the authorization provided by the scopes of the token.

The following actors are involved in setting up an application to use OAuth 2.0 and OpenID Connect to store and retrieve FHIR resources from FHIR Server. In many cases, especially early in development, one individual might fill more than one role.

Role Responsibilities
Identity Provider Administrator When an external Identify Provider (IdP) is being used for authentication, the IdP Administrator must register the application with the IdP before FHIR Server Administrator can configure the authentication server and application in the Cloud Services Portal. The IdP Administrator is also responsible for adding application users to the IdP so their credentials can be verified in order to issue an access token.
FHIR Server Administrator FHIR Server Administrator is responsible for configuring the authentication server and application in the Cloud Services Portal and providing the configuration details to the Application Developer. If using the integrated authentication server, FHIR Server Administrator also defines the FHIR scopes that the application will be specifying in its request for a token.
Application Developer The Application Developer is responsible for creating the application, such as a SMART on FHIR app, that accesses FHIR Server data. The Application Developer takes the access details of the application’s configuration and modifies values of a SMART app’s authorization methods to obtain access tokens.

When the access token accompanying a request includes a scope to access data in a specific Patient’s compartment, it is the application’s responsibility to set the correct patient context value. For example, if the application user should only be able to view resources pertaining to Patient 1497, then the application must properly set the patient context value to 1497.

Though the Identity Provider Adminstrator or FHIR Server Administrator defines what scopes are possible, it is the Application Developer’s responsibility to ensure that a user’s request includes the proper scopes in order to protect Protected Health Information (PHI).

Set Up Access Controls

Once you have created your FHIR Server deployment and chosen API keys or OAuth 2.0 as an authentication and authorization strategy, you need to set up the access controls needed to govern how users and applications can access the service.

For more information on API keys and OAuth 2.0, see the Authentication and Authorization section of this document.

Create API Keys

API keys can be used to authenticate FHIR requests to FHIR Server. Each new user is assigned a unique API key that is sent in the header of the request to allow access to the service.

You can create and manage API keys on the Credentials page for your deployment.

Set Up OAuth 2.0

To use OAuth 2.0, you need to configure an authentication server and one or more associated applications.

The authentication server is used to authenticate users of your service and can be the integrated authentication server or an external authentication server. The integrated authentication server, built on Amazon Cognito, gives you a quick way to get up and running with FHIR Server. An external authentication server is the preferred solution for organizations that have an existing identity provider (often called an IdP) that can be used to manage users and provide authentication.

An application is a means of tying a FHIR-enabled application to the authentication server. If you are using the integrated authentication server, creating an application allows you to define an authentication flow, as well as set up the scopes that will be used to provide the user with the authorization needed to access the required FHIR resources. If you are using an existing IdP, you need to set up the application in the administrative console of your IdP. Configuring the application in the Cloud Services Portal is then a matter of entering the Client ID and Client Secret of your application, as determined by your IdP.

You can configure an authentication server and its associated applications on the OAuth 2.0 page for your deployment.

If you are using the integrated authentication server, you must also create users who will be permitted to log in to the authentication server in order for them to use the application to access FHIR Server. You can create users on the Credentials page for your deployment.

Next sectionInterSystems FHIR Server Reference Information
FeedbackOpens in a new tab