Commure FHIR API

Version
1.0
Release Date
2020-02-06
Status
Live

Commure provides a RESTful API for developers to simplify accessing, securing, and modifying healthcare data. Our server complies to the HL7 FHIR standard and is built according to industry best practices.

Why FHIR?

FHIR is a standard specified by HL7 to increase availability, discoverability, and understanding of how to model healthcare data. FHIR’s popularity has been growing as more healthcare records are becoming digitized and need to be shared across systems and networks. By building your application against the FHIR specification, you are preparing your app for the future of healthcare software.

What is FHIR?

At its core, FHIR is composed of two parts:

  1. The Data Models for Healthcare Resources
  2. A RESTful API for managing those resources

FHIR itself defines hundreds of resources and dozens of operations, but also allows the flexibility for developers to extend and constrain the specification for their requirements.


Introductory Walkthrough

To better understand what these resources and operations look like, it’s useful to walk through an example:

Let’s say we need to schedule a patient’s appointments.

To start, we need to know how to store a patient. FHIR defines a Patient definition to model what can be specified for a patient. According to the spec, a Patient can have a name, a gender, a birthdate, ... (See here for more). To keep it simple, let’s start by representing a Patient with a name:

{
"resourceType": "Patient",
"name": [
{
"use": "official",
"family": "Salk",
"given": ["Jonas"]
}
]
}

The "name" entry might look more complicated than you were anticipating. That’s because name is defined on a FHIR Patient resource as a "HumanName" type. FHIR defines different data types to simplify defining these resource structures. The HumanName datatype has its own fields, just like a FHIR resource. (You can read about the different datatypes defined by FHIR here).

Now that we set up the data in a way that our FHIR server could understand, we can send the resource to our server. This is what’s referred to in REST APIs as a create operation.

FHIR defines this operation and the rest of the REST operations by default. To create the operation, you can submit the body of the Patient we’ve created above as a POST request to /Patient. (To read about the other operations FHIR allows, see FHIR Operations.)

If creating this Patient resource is a success, you should see a 201 CREATED status returned and the response body will contain the full Patient resource we saved to the database. Inside this body, you can find an ID was assigned to the resource. We’ll need this ID to reference the Patient when scheduling an Appointment for the Patient.

Now creating an Appointment should look very similar to the process we used to create the Patient.

We set up a FHIR JSON body for the resource we want to create:

{
"resourceType": "Appointment",
"Participant": [
{
"Actor": "Patient/{PatientId}",
"Status": "accepted"
}
]
}

Now we can use the RESTful create endpoint, POST /Appointment to create the appointment resource.

...

Uh oh! The response probably wasn’t a 201 CREATED this time. Instead, you should have seen a 401. This is because the resource you posted was not valid.

To find out why, you can read the response from the request. Certain fields in FHIR are strict about having either at most one or exactly one element. To know what FHIR requires, you can check the field's cardinality. Although this can make modifying data more complicated, keeping the data in a valid state helps to ensure that apps will not encounter data in shapes and conditions they were not expecting.

To solve our issue for the Appointment, we can set the status field in addition to what we had before.

{
"resourceType": "Appointment",
"Status": "booked",
"Participant": [
{
"Actor": "Patient/{PatientId}",
"Status": "accepted"
}
]
}

Now when you POST this resource, it should behave as expected and return a 201.

So far, we have a Patient and an Appointment scheduled for that Patient. What happens when we want to update the Appointment when it’s finished?

To update the Appointment resource, we can submit the full Appointment resource as a PUT request (or an update operation as defined by REST) with the updated status code:

PUT /Appointment/{AppointmentId}

{
"resourceType": "Appointment",
"Status": "fulfilled",
"Participant": [
{
"Actor": "Patient/{PatientId}",
"Status": "accepted"
}
]
}

This should give you a quick overview of how to work with FHIR, but you can read more about all of the resources and operations it supports and try it out for yourself!

Related Reading

Working with FHIR
Quick Start