GraphQL has been used in rich SPA and mobile apps for years. The advantages GraphQL over REST are leading to rapid adoption of GraphQL for APIs. Healthcare developers were limited to REST for accessing HL7 FHIR data. Operational security in front of FHIR endpoints has also resulted in few rich healthcare SPA/mobile apps that use FHIR.  After all, there are a lot of paths and protocols that need to be vigorously researched and protected before distributed SPA/mobile apps are allowed to access FHIR over the internet. 

 

But we, as consumers, want RICH, MODERN, SECURE apps!  We expect Mobile first, and SPA second.

 

Introducing Graphir

 

Graphir is a starting point to bring GraphQL to healthcare. Graphir is an opensource .NET sample project to help you get started using GraphQL to access FHIR today.  It implements GraphQL using the HotChocolate library. 

Graphir sits between your distributed SPA/mobile apps and a FHIR endpoint. Graphir can easily be protected with an Azure API manager for additional protection. 

 

Graphir enables developers to use GraphQL to fetch complex FHIR objects! No more spending hours researching which REST call to make and optimizing the body of that call.  Simply ctrl + space your way to a query in seconds!

Graphir enables developers to fetch multiple, different FHIR resources with a single call! No more fetching Patients, THEN fetching the Practitioners associated with those Patients.

Graphir enables developers to use GraphQL caching to dramatically improve performance and reduce computer costs at the FHIR endpoint. No more going to the FHIR endpoint for static data like birthdates.

Graphir enables developers to use GraphQL to fan out requests to other APIs, allowing a single endpoint for all the data your app needs. No more FHIR endpoint + user preference endpoint + app config endpoint etc.

 

Let’s get started by getting Graphir running on your local environment!

Getting Started With Graphir

Clone the Graphir repo. 

Follow these instructions.

Simply hit F5 in Visual Studio, or use dotnet run

Getting a Token

Since Graphir uses authentication you’ll need to get a token to access Graphir. Follow these steps to get a token using Postman.

Writing our First GraphQL Query

Now that it’s running let’s go to http://localhost:5080/graphql

 

The IDE here is Banana Cake Pop (tutorial). First, we need to register our token:

Click on this gear

 

 

Open the Authorization Tab, select Bearer and paste in your token

 

Now we can write our first query.

 

 

 

 

 

query{me}

 

 

 

 

 

This simple query returns the name of the user who’s token we’ve provided.

 

Fetching List of Patients

Let’s write a query to get all the patients.   Instead of copy/pasting, try using ctrl + space to autocomplete.

 

 

 

 

 

 

query {
  PatientList{
    id
    name{ family given}
  }
}

 

 

 

 

 

On our FHIR endpoint this returns a list of patients:

 

 

Fetch Patient and their Practitioner in a single call

Let’s modify the query a bit to show the power of GraphQL. In our client app, we don’t want given and family names, we want first and last names. So, let’s alias the fields. We can alias any field by prepending the field with our desired name and a colon. So instead of given we use last:given.  Now our query looks like this:

 

 

 

 

 

query {
  PatientList{
    id
    name{ last:family first:given}
  }
}

 

 

 

 

 

The results of the query are now altered- but we didn't change any code!  Just the query!

 

For our frontend devs, this small bit of functionality is huge! Our frontend app doesn’t have to map fields to rename them. Instead, we just change our query, and the data comes to our app in the right format!  We don’t even have to talk to our app’s API provider- we make the change and things just work.

 

But our app is going to display each patient’s General Practitioner.  In a traditional REST app, we’d fetch all the Patients and then for each Patient find their Practitioner.  But with the power of GraphQL  we can get all the info in a single call. Our modified query looks like:

 

 

 

 

 

query {
  PatientList{
    id
    name{ last:family first:given}
    GP:generalPractitioner{
      name{first:given last:family}
    }
  }
}

 

 

 

 

 

 

In our FHIR endpoint this returns patients and their GPs.  Note the following patient that has two GPs.

 

 

 

How does this work? The GraphQL middleware makes the mapping calls for us with a resolver.

Again, this means you can spend less time figuring out how to fetch data and more time doing things with the data.  Deliver your value faster!

Where to go from here

You can use the same pattern we used in Graphir to implement additional FHIR objects, for example occurrence. You can use Banana Cake Pop for development, but you’ll need a client for your app. Refer to this guide for choosing a client for your .NET GraphQL. But most importantly get started developing!  You can see our Graphir code in our FHIR Blaze app.