Getting Started with FHIR and GraphQL
A Step-by-Step Guide
Feb 04, 2019

GraphQL and FHIR are two emerging technologies that we’re passionate about. In fact, we recently flew to Amsterdam for FHIR DevDays to give a talk on how to integrate GraphQL into FHIR.

If you’re interested in playing around with these technologies too, you’re in luck – we created an open source server in Node.js. It’s a simple facade server, and a great starting point to get involved with FHIR. In this article, we’ll walk you through our server codebase, setting up the server, and writing your first resolver.

Getting started

The best way to get started is to check out the Github page where you can read our docs, ask questions, or submit issues. In addition, you can clone the Git repo and follow the instructions below.


  • Install Git: You can find installation instructions here.
  • Install Node: Get the latest LTS version here.
  • Install Yarn: We use Yarn in place of npm and think you should too. Installation instructions can be found here.

Once you’ve finished the prerequisites, clone the repo and start a local development server.

# Clone the Repository
$ git clone

# Install the dependencies
$ cd graphql-fhir
$ yarn install

# Run the development server
$ yarn nodemon

Setting up the development server will expose some graphql endpoints as well as the Graphiql explorer application for DSTU2, STU3, and R4. Also, if you edit any files, the server will automatically restart for you. Since R4 is the latest, check out Graphiql explorer for R4 now here.

You should now see an interface that looks like this:

The left hand section is where you will write your queries. The middle section is where you will see your results when you execute your query, and the right section is the documentation explorer. Feel free to click around and familiarize yourself with this. Graphiql is a powerful developer tool to have when developing a GraphQL API.

How do I run a query?

To execute your first query, add the following query to the left panel of the Graphiql interface and hit the execute query button (looks like a play icon).

query {
Patient {
name {given}

Graphiql should now look like this:

What’s with all the nulls in the data?

By default, our server returns empty objects in all the resolvers. This allows the queries to execute without worrying about database connections or writing complex query statements. However, in order to make this useful, we need to integrate a data source. For the sake of brevity, in this article we will wire up a mock data source and return data through the patient resolver. In a more realistic situation, you’ll need to connect a database. To learn more about this, authentication (SMART on FHIR), and other topics, please see our FAQ.

Let’s implement our first resolver

As we previously mentioned, all of our resolvers are stubbed out. To implement a mock data source and a resolver, we’ll be downloading an example FHIR patient record from HL7 and integrating into our server. You can find the record we’re using here. Download this json file and save it in your code at src/resources/4_0_0/profiles/patient/patient-example.json.

First, we need to write some resolver logic. When a GraphQL query gets executed, it will eventually invoke your resolver and it’s up to this resolver to get the data and return it in the expected format. Open the src/resources/4_0_0/profiles/patient/resolver.jsfile. Next, add in a require statement for some error utilities. We provide some simple utilities to wrap an OperationOutcome in a GraphQL error for you so you don’t have to every time.

Add const errorUtils = require('../../../../utils/error.utils.js'); at the very top of src/resources/4_0_0/profiles/patient/resolver.js. Next, locate the getPatient function.

Let’s change the code there to look like the code below:

module.exports.getPatient = function getPatient(
	context = {},
) {
	let { server, version, req, res } = context;
	let patient = {};

	try {
		patient = require(`./patient-${args._id}.json`);
	} catch (err) {
		let error = errorUtils.notFound(version, err.message);
		return errorUtils.formatErrorForGraphQL(error);

	return patient;

Run one more query

Let’s run one more query to test that we wired things up correctly.

query {
Patient(_id:"example") {
name {given}

You should now see the following:


Good Job! You now have FHIR data flowing through a GraphQL API. Check out our FAQ’s for some next steps. You can also view the current draft of the GraphQL FHIR Specification here.