FHIR APIs | FHIR® tutorials

Working with APIs for FHIR

If you're a developer, or just someone interested in coding with FHIR, then this is the page for you to read! In this tutorial we'll walk you through doing all of the tutorials you've been doing with Postman programatically.

This tutorial requires technical knowledge to do! If you're not technically minded, you can still learn FHIR by doing other tutorials on this website.

Click the apropirate button below depending on which programming language you are intrested in. This will help this web site display the examples most relevant to your choice.

Step 1: Setup

Step 2: Create a basic Patient

Step 3: Upload your basic Patient

Step 4: Search for a resource

Step 5: Run an operation

Step 1: Setup

FHIR provides some official API code libaraies in Java and .Net to help you work with the standard.

They are:

Java

HAPI FHIR library: To get started with HAPI, add the dependency via Maven or Gradle - or just download the library locally. If you've done the latter, include all non-hapi jars in your classpath, and only hapi-fhir-base-2.3.jar, hapi-fhir-structures-dstu3-2.3.jar, hapi-fhir-validation-resources-dstu3-2.3.jar hapi ones if you're working with STU3.

The Java examples listed in this tutorial require Java 8 SDK installed, however HAPI itself supports Java all the way back to 6.

Microsoft .Net

FHIR .NET API: The simplest way to get started with the .Net API is to search for it in the Nuget pacakge manager built into Visual Studio. Right click your Solution and select 'Manage Nuget Packages' and then search and install both 'Hl7.Fhir.STU3' and 'Hl7.FluentPath'. You may also need to select the 'Include prerelease' if you wish to have the latest STU3 release. You can find a C# project here on GitHub that contans all the C# examples seen below.

Step 2: Create a basic Patient

Upon creating a new project, you'll see a new blank class not much different from this:

C# Java

using System;
using System.Collections.Generic;

namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
       // write your code here
    }
  }
}

package com.myhotcompany;

public class Main {

    public static void main(String[] args) {
	// write your code here
    }
}

Create a basic Patient resource and populate it with some information. Running this code will print the resource as XML for you:

C# Java

using System;
using System.Collections.Generic;
using System.Xml.Linq;
namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      var MyPatient = new Hl7.Fhir.Model.Patient();

      //Patient's Name
      var PatientName = new Hl7.Fhir.Model.HumanName();
      PatientName.Use = Hl7.Fhir.Model.HumanName.NameUse.Official;
      PatientName.Prefix = new string[] { "Mr" };
      PatientName.Given = new string[] { "Sam" };
      PatientName.Family = "Fhirman";
      MyPatient.Name = new List<Hl7.Fhir.Model.HumanName>();
      MyPatient.Name.Add(PatientName);

      //Patient Identifier 
      var PatientIdentifier = new Hl7.Fhir.Model.Identifier();
      PatientIdentifier.System = "http://ns.electronichealth.net.au/id/hi/ihi/1.0";
      PatientIdentifier.Value = "8003608166690503";
      MyPatient.Identifier = new List<Hl7.Fhir.Model.Identifier>();
      MyPatient.Identifier.Add(PatientIdentifier);

      Console.WriteLine("Press any key to serialise Resource to the console as XML.");
      Console.ReadKey();
      Console.WriteLine("");
      try
      {
        //attempt to serialize the resource
        string xml = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToXml(MyPatient);
        XDocument xDoc = XDocument.Parse(xml);
        Console.Write(xDoc.ToString());
        Console.WriteLine("");
        Console.WriteLine("");
      }
      catch (Exception Exec)
      {
        Console.Write("Error message: " + Exec.Message);
      }
      Console.Write("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import org.hl7.fhir.dstu3.model.HumanName;
import org.hl7.fhir.dstu3.model.Patient;

import java.io.IOException;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see http://hapifhir.io/doc_intro.html
        FhirContext ctx = FhirContext.forDstu3();

        Patient patient = new Patient();

        // you can use the Fluent API to chain calls
        // see http://hapifhir.io/doc_fhirobjects.html
        patient.addName().setUse(HumanName.NameUse.OFFICIAL)
                .addPrefix("Mr").addFamily("Fhirman").addGiven("Sam");
        patient.addIdentifier()
                .setSystem("http://ns.electronichealth.net.au/id/hi/ihi/1.0")
                .setValue("8003608166690503");

        System.out.println("Press Enter to serialise Resource to the console as XML.");
        System.in.read();

        // create a new XML parser and serialize our Patient object with it
        String encoded = ctx.newXmlParser().setPrettyPrint(true)
                .encodeResourceToString(patient);

        System.out.println(encoded);

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Once run, you should see something like this:

If your IDE supports code completion, try using it to explore the Patient resource and populate it with some information such as the gender, birthday and phone number. Otherwise, consult the FHIR Patient page to see what can you populate your resource with (Javadoc is also available).

Step 3: Upload your basic Patient

Now that we can create a simple resource, let's upload it to a FHIR server:

C# Java

using System;
using System.Collections.Generic;
using System.Xml.Linq;
namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      //The fhir server end point address      
      string ServiceRootUrl = "https://hapi.fhir.org/baseDstu3";

      //Create a patient resource instance
      var MyPatient = new Hl7.Fhir.Model.Patient();

      //Patient's Name
      var PatientName = new Hl7.Fhir.Model.HumanName();
      PatientName.Use = Hl7.Fhir.Model.HumanName.NameUse.Official;
      PatientName.Prefix = new string[] { "Mr" };
      PatientName.Given = new string[] { "Sam" };
      PatientName.Family = "Fhirman" ;
      MyPatient.Name = new List<Hl7.Fhir.Model.HumanName>();
      MyPatient.Name.Add(PatientName);

      //Patient Identifier 
      var PatientIdentifier = new Hl7.Fhir.Model.Identifier();
      PatientIdentifier.System = "http://ns.electronichealth.net.au/id/hi/ihi/1.0";
      PatientIdentifier.Value = "8003608166690503";
      MyPatient.Identifier = new List<Hl7.Fhir.Model.Identifier>();
      MyPatient.Identifier.Add(PatientIdentifier);

      //Create a client to send to the server at a given endpoint.
      var FhirClient = new Hl7.Fhir.Rest.FhirClient(ServiceRootUrl);

      // increase timeouts since the server might be powered down
      FhirClient.Timeout = (60 * 1000);

      Console.WriteLine("Press any key to send to server: " + ServiceRootUrl);
      Console.ReadKey();
      try
      {
        //Attempt to send the resource to the server endpoint
        Hl7.Fhir.Model.Patient ReturnedPatient = FhirClient.Create<Hl7.Fhir.Model.Patient>(MyPatient);
        Console.WriteLine(string.Format("Resource is available at: {0}", ReturnedPatient.Id));
        Console.WriteLine();
        Console.WriteLine("This is what we sent up: ");
        Console.WriteLine();
        string xml = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToXml(MyPatient);
        XDocument xDoc = XDocument.Parse(xml);
        Console.WriteLine(xDoc.ToString());
        Console.WriteLine();
        Console.WriteLine("This is what we received back: ");
        Console.WriteLine();
        xml = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToXml(ReturnedPatient);
        xDoc = XDocument.Parse(xml);
        Console.WriteLine(xDoc.ToString());
        Console.WriteLine();
      }
      catch (Hl7.Fhir.Rest.FhirOperationException FhirOpExec)
      {
        //Process any Fhir Errors returned as OperationOutcome resource
        Console.WriteLine();
        Console.WriteLine("An error message: " + FhirOpExec.Message);
        Console.WriteLine();
        string xml = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToXml(FhirOpExec.Outcome);
        XDocument xDoc = XDocument.Parse(xml);
        Console.WriteLine(xDoc.ToString());
      }
      catch (Exception GeneralException)
      {
        Console.WriteLine();
        Console.WriteLine("An error message: " + GeneralException.Message);
        Console.WriteLine();
      }
      Console.WriteLine("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.parser.DataFormatException;
import ca.uhn.fhir.parser.IParser;
import ca.uhn.fhir.rest.api.MethodOutcome;
import ca.uhn.fhir.rest.client.IGenericClient;
import org.hl7.fhir.dstu3.model.*;

import java.io.IOException;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see http://hapifhir.io/doc_intro.html
        FhirContext ctx = FhirContext.forDstu3();
        String serverBaseUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";

        Patient ourPatient = new Patient();

        // you can use the Fluent API to chain calls
        // see http://hapifhir.io/doc_fhirobjects.html
        ourPatient.addName().setUse(HumanName.NameUse.OFFICIAL)
                .addPrefix("Mr").addFamily("Fhirman").addGiven("Sam");
        ourPatient.addIdentifier()
                .setSystem("http://ns.electronichealth.net.au/id/hi/ihi/1.0")
                .setValue("8003608166690503");

        // increase timeouts since the server might be powered down
        // see http://hapifhir.io/doc_rest_client_http_config.html
        ctx.getRestfulClientFactory().setConnectTimeout(60 * 1000);
        ctx.getRestfulClientFactory().setSocketTimeout(60 * 1000);

        // create the RESTful client to work with our FHIR server
        // see http://hapifhir.io/doc_rest_client.html
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);

        System.out.println("Press Enter to send to server: " + serverBaseUrl);
        System.in.read();

        try {
            // send our resource up - result will be stored in 'outcome'
            // see http://hapifhir.io/doc_rest_client.html#Create_-_Type
            MethodOutcome outcome = client.create()
                    .resource(ourPatient)
                    .prettyPrint()
                    .encodedXml()
                    .execute();

            IdType id = (IdType) outcome.getId();
            System.out.println("Resource is available at: " + id.getValue());

            IParser xmlParser = ctx.newXmlParser().setPrettyPrint(true);
            Patient receivedPatient = (Patient) outcome.getResource();
            System.out.println("This is what we sent up: \n"
                    + xmlParser.encodeResourceToString(ourPatient)
                    + "\n\nThis is what we received: \n"
                    + xmlParser.encodeResourceToString(receivedPatient));
        } catch (DataFormatException e) {
            System.out.println("An error occurred trying to upload:");
            e.printStackTrace();
        }

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Comparing the resource that we sent up to the resource we received back, you'll notice that the server generated a basic narrative for us from the data available and also added its logical ID

Step 4: Search for a resource

Now that you've uploaded a resource, try searching for it. Remember that you'll get a bundle back with many entries, one resource per entry.

C# Java

using System;
using System.Collections.Generic;
using System.Xml.Linq;
namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      //The fhir server end point address      
      string ServiceRootUrl = "https://hapi.fhir.org/baseDstu3";
      //Create a client to send to the server at a given endpoint.
      var FhirClient = new Hl7.Fhir.Rest.FhirClient(ServiceRootUrl);
      // increase timeouts since the server might be powered down
      FhirClient.Timeout = (60 * 1000);

      Console.WriteLine("Press any key to send to server: " + ServiceRootUrl);
      Console.WriteLine();
      Console.ReadKey();
      try
      {
        //Attempt to send the resource to the server endpoint
        Hl7.Fhir.Model.Bundle ReturnedSearchBundle = FhirClient.Search<Hl7.Fhir.Model.Patient>(new string[] { "family=Fhirman" });
        Console.WriteLine(string.Format("Found: {0} Fhirman patients.", ReturnedSearchBundle.Total.ToString()));
        Console.WriteLine("Their logical IDs are:");
        foreach (var Entry in ReturnedSearchBundle.Entry)
        {
          Console.WriteLine("ID: " + Entry.Resource.Id);
        }
        Console.WriteLine();
      }
      catch (Hl7.Fhir.Rest.FhirOperationException FhirOpExec)
      {
        //Process any Fhir Errors returned as OperationOutcome resource
        Console.WriteLine();
        Console.WriteLine("An error message: " + FhirOpExec.Message);
        Console.WriteLine();
        string xml = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToXml(FhirOpExec.Outcome);
        XDocument xDoc = XDocument.Parse(xml);
        Console.WriteLine(xDoc.ToString());
      }
      catch (Exception GeneralException)
      {
        Console.WriteLine();
        Console.WriteLine("An error message: " + GeneralException.Message);
        Console.WriteLine();
      }
      Console.WriteLine("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.model.primitive.IdDt;
import ca.uhn.fhir.rest.client.IGenericClient;
import org.hl7.fhir.dstu3.model.*;

import java.io.IOException;
import java.util.List;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see http://hapifhir.io/doc_intro.html
        FhirContext ctx = FhirContext.forDstu3();
        String serverBaseUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";

        // increase timeouts since the server might be powered down
        // see http://hapifhir.io/doc_rest_client_http_config.html
        ctx.getRestfulClientFactory().setConnectTimeout(60 * 1000);
        ctx.getRestfulClientFactory().setSocketTimeout(60 * 1000);

        // create the RESTful client to work with our FHIR server
        // see http://hapifhir.io/doc_rest_client.html
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);

        System.out.println("Press Enter to send to server: " + serverBaseUrl);
        System.in.read();

        try {
            // perform a search for Patients with last name 'Fhirman'
            // see http://hapifhir.io/doc_rest_client.html#SearchQuery_-_Type
            Bundle response = client.search()
                    .forResource(Patient.class)
                    .where(Patient.FAMILY.matches().values("Fhirman"))
                    .returnBundle(Bundle.class)
                    .execute();

            System.out.println("Found " + response.getTotal()
                    + " Fhirman patients. Their logical IDs are:");
            response.getEntry().forEach((entry) -> {
                // within each entry is a resource - print its logical ID
                System.out.println(entry.getResource().getIdElement().getIdPart());
            });
        } catch (Exception e) {
            System.out.println("An error occurred trying to search:");
            e.printStackTrace();
        }

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Step 5: Run an operation

Lastly, let's execute an operation on the server. A simple operation we can do is the Patient/$everything - this'll fetch us the Patient resource and all related resources to it.

Firstly, lets upload the sample Patient we've explored before in the Patient with References tutorial:

Now we can run a query on the operation to get a Bundle with the Patient and associated resources. Here's how it looks in code. Make sure to update MY_PATIENT_ID with (press Upload first).

C# Java

using System;
using System.Collections.Generic;
using System.Xml.Linq;
namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      //The fhir server end point address      
      string ServiceRootUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";     
      //Create a client to send to the server at a given endpoint.
      var FhirClient = new Hl7.Fhir.Rest.FhirClient(ServiceRootUrl);      
      // increase timeouts since the server might be powered down
      FhirClient.Timeout = (60 * 1000);

      Console.WriteLine("Press any key to send to server: " + ServiceRootUrl);
      Console.WriteLine();
      Console.ReadKey();
      try
      {
        //Attempt to send the resource to the server endpoint                
        UriBuilder UriBuilderx = new UriBuilder(ServiceRootUrl);
        UriBuilderx.Path = "Patient/MY_PATIENT_ID";
        Hl7.Fhir.Model.Resource ReturnedResource = FhirClient.InstanceOperation(UriBuilderx.Uri, "everything");

        if (ReturnedResource is Hl7.Fhir.Model.Bundle)
        {
          Hl7.Fhir.Model.Bundle ReturnedBundle = ReturnedResource as Hl7.Fhir.Model.Bundle;
          Console.WriteLine("Received: " + ReturnedBundle.Total + " results, the resources are: ");          
          foreach (var Entry in ReturnedBundle.Entry)
          {
            Console.WriteLine(string.Format("{0}/{1}",Entry.Resource.TypeName, Entry.Resource.Id));
          }
        }
        else
        {
          throw new Exception("Operation call must return a bundle resource");
        }
        Console.WriteLine();

      }
      catch (Hl7.Fhir.Rest.FhirOperationException FhirOpExec)
      {
        //Process any Fhir Errors returned as OperationOutcome resource
        Console.WriteLine();
        Console.WriteLine("An error message: " + FhirOpExec.Message);
        Console.WriteLine();
        string xml = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToXml(FhirOpExec.Outcome);
        XDocument xDoc = XDocument.Parse(xml);
        Console.WriteLine(xDoc.ToString());
      }
      catch (Exception GeneralException)
      {
        Console.WriteLine();
        Console.WriteLine("An error message: " + GeneralException.Message);
        Console.WriteLine();
      }
      Console.WriteLine("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.IGenericClient;
import ca.uhn.fhir.rest.client.interceptor.LoggingInterceptor;
import org.hl7.fhir.dstu3.model.*;

import java.io.IOException;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see http://hapifhir.io/doc_intro.html
        FhirContext ctx = FhirContext.forDstu3();
        String serverBaseUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";

        // increase timeouts since the server might be powered down
        // see http://hapifhir.io/doc_rest_client_http_config.html
        ctx.getRestfulClientFactory().setConnectTimeout(60 * 1000);
        ctx.getRestfulClientFactory().setSocketTimeout(60 * 1000);

        // create the RESTful client to work with our FHIR server
        // see http://hapifhir.io/doc_rest_client.html
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);

        client.registerInterceptor(new LoggingInterceptor(true));

        System.out.println("Press Enter to send to server: " + serverBaseUrl);
        System.in.read();

        try {
            // Invoke $everything on our Patient
            // See http://hapifhir.io/doc_rest_client.html#Extended_Operations
            Parameters outParams = client
                    .operation()
                    .onInstance(new IdType("Patient", "MY_PATIENT_ID"))
                    .named("$everything")
                    .withNoParameters(Parameters.class) // No input parameters
                    .execute();

            // FHIR normally returns a 'Parameters' resource to an operation, but
            // in case of a single resource response, it just returns the resource
            // itself. This is why it seems that we have to fish a Bundle out of the
            // resulting Params result - HAPI needs to update for the FHIR shortcut
            Bundle result = (Bundle) outParams.getParameterFirstRep().getResource();

            System.out.println("Received " + result.getTotal()
                    + " results. The resources are:");
            result.getEntry().forEach((entry) -> {
                Resource resource = entry.getResource();
                System.out.println(resource.getResourceType() + "/"
                        + resource.getIdElement().getIdPart());
            });
        } catch (Exception e) {
            System.out.println("An error occurred trying to run the operation:");
            e.printStackTrace();
        }

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Try running the code and you should see the same IDs for related resources as on this page:

Patient/(press Upload first)

Encounter/(press Upload first)

Observation/(press Upload first)

Observation/(press Upload first)

DiagnosticReport/(press Upload first)

That's about it for the basics! Happy coding. Check out the HAPI documentation if you're using Java for more as well.

Working with APIs for FHIR

Click the apropirate button below depending on which programming language you are intrested in. This will help this web site display the examples most relevant to your choice.

Contents

Step 1: Setup

Step 2: Create a basic Patient

Step 3: Upload your basic Patient

Step 4: Search for a resource

Step 5: Run an operation