Learn more about a new sample app that uses FHIR APIs.

The American Heart Association have released the 2017 Heart and Stroke Statistics and one of the more striking statistics, was that Heart Disease (including Coronary Heart Disease, Hypertension, and Stroke) remains to be the number one cause of death in the US. The Association tracks seven key health factors and behaviours that increases the risk for heart disease. To improve cardiovascular health, they advocate a concept called Life’s Simple 7: not-smoking, physical activity, healthy diet, monitoring body weight and cholesterol control, blood pressure, and blood sugar.

Orion Health has developed a new demo app that uses HL7®FHIR®. The application is an implementation of the Framingham Cardiovascular risk calculator. It works by taking a number of measures–blood lipid levels, blood pressure, smoking status and whether an individual is a diabetic–and assigning a number of points to each one (there can be negative points for good results as well). The points are totalled and the overall risk calculated, then saved back to the platform, enabling it to be viewed directly from a portal. 

In last week’s post How can FHIR APIs help to prevent heart attacks? we described the overall operation of our sample application. Now, let’s explore the actual APIs exposed by the platform that we’re going to need.

We’ll consider each of these in turn. Note that these calls are made from the Node.js server to the platform. The server itself exposes API endpoints that the client app calls from the browser. For this reason, you won’t see the calls to the platform in the browser history.

Note also that any calls to the platform must include an access token that is issued by the platform after logging in. So you must log in first to be able to access any data (this process is described in the next post)

Get User Details

Currently this is not a FHIR API (And there are no plans to create one as user management is considered outside the scope of FHIR). Orion Health supplies the following query to retrieve the details of the currently logged in user.

GET [API endpoint]/Actor/current

The actual response is specific to Orion Health – but straightforward to understand.

Get worklists for User

Again, this is specific to Orion Health.

GET [API endpoint]/Actor/{user identifier}/patientlist/watchlist

The user identifier comes from the previous API call – get user details.

Get worklist details

GET [API endpoint]/Actor/{user identifier}/patientlist/watchlist/{listIdentifier]

The list identifier comes from the ‘get worklist’ call. In this app, the node.js server transforms the response from the platform into a FHIR bundle of Patient resources, so that the client does not need to understand the Orion Health-specific nature of the contents.

Get Patient details

This is a true FHIR endpoint exposed by the platform. Because the actual patient information that we have is their identifier, it is actually a search against Patient with the identifier as a parameter, and returning a Bundle with (hopefully) a single Patient. Here’s the call:

GET [API endpoint]/Patient?identifier={}

And note that the identifier is in the FHIR format – {system}|{value}.

The server extracts the Patient from the bundle and returns to the client.

Get Oberservations for a client

This is another FHIR endpoint exposed by the platform. We have a couple of options for using it in this scenario. The endpoint does support query for specific values, so we could just query for the values that we want – and that would be the best solution. However, there are 5 different codes that we are after, so to be performant we’ll need to ‘parallelize’ the calls to the platform.

Given that this is just a demo, we went for the easier approach of retrieving all the Observations for the patient from the platform, and filtering them in the nodejs server. If this were a ‘real’ server, we’d make the separate parallel calls.

Here’s the call:

GET [API endpoint]/Observation?subject.identifier = {}

Note that this is what is technically called a ‘chained’ request – we want Observations where the subject of the Observation has specific characteristics (a given identifier). See http://hl7.org/fhir/search.html#chaining for more details about chaining. As a side note, the spec also defines a ‘patient’ search parameter which queries on subject where the subject is a Patient – so an equivalent query would be Observation?patient.identifier={}. However, this is not implemented in the platform.

(Since I wrote this blog, I actually did modify the server to make multiple calls asynchronously as an exercise. I could have also used a single query specifying multiple codes – but I did it the hard way!)

Get Conditions for Patient

Very similar to getting observations – and the same comments about searching for a specific code or filtering on the server apply.

GET [API endpoint]/Condition?subject.identifier = {}

An interesting question here is determining which condition.code represents diabetes, as there are a multitude of possible codes depending on the terminology being used and the level of detail of the Condition. This is a separate discussion – for the purposes of this app we just chose an example one.

Write Observation

This is the only write API that we’re using in this example (and, at the item of writing, the only write operation that we support). It’s a straightforward POST operation, the only tricky bit being that we need to get the reference to the patient using the Patient.id element of the GET Patient operation described above when we create the Observation resource.

POST [API endpoint]/Observation

So that all the APIs we need!

In next weeks’ post we will discuss the security aspects of this interaction using OAuth. 

To learn more about FHIR for Clinicians download the white paper now.

Go to White Paper