Make Your First FHIR Client —within One Hour!

This post was originally published on May 10, 2015 by Rob Mulders and updated on January 17, 2022 by Marten Smits.

People keep asking us:

“Is it really that simple to write an application that can send and retrieve FHIR data from a server?”

In this blog we would like to share with you 4 easy steps to create a very simple console application to send and retrieve FHIR data: a simple FHIR client. At the end of this tutorial you’ll be able to create a FHIR client that connects to a FHIR server on the internet, sends data to that server, and after that, fetches all the patients containing “John” in their names from the server to show them in a console application.

Step 1 – Create a project

This step assumes you have Visual Studio ready on your machine. Fire up Visual Studio without any old project open. Choose “Create a new project”, and then “Console App”. Name your project whatever you like, and click OK. Visual Studio creates a solution with a  single class called “Program.cs”.

Step 2 – Get the .NET SDK for connecting to FHIR servers

Since your program wants to connect to a FHIR server without doing complex stuff yourself, you will need the Firely .Net SDK. On the menu, choose Project – Manage NuGet Packages. Click “Browser” and type “FHIR” in the search box. A list of NuGet packages related to FHIR will appear. Make sure you choose “Hl7.Fhir.R4“, which contains the basic FHIR functionalities for FHIR release 4 (R4), the version we will use during this tutorial. Then click on Install. If everything is ok, a green marker will appear. You can close the NuGet manager.

Step 3 – Posting patient information to a FHIR server

Now we can actually start programming. Open Program.cs. We are going to send a FHIR representation of a Patient (a Patient resource) to a FHIR test server. Note that the server we are using is a public test server, so make sure you don’t send any real world data.

First we are going to add the following line at the top of the program to indicate that we are going to use the model and client components of the Firely .NET SDK:

using Hl7.Fhir.Model;
using Hl7.Fhir.Rest;

Next, we are going to create a new Patient, with a patient ID, name, gender, and birthdate inside the program itself. It will look like this:

using Hl7.Fhir.Model;
using Hl7.Fhir.Rest;

namespace MyFirstFhirClient
{
    internal class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("This is my first FHIR Client");

            var patient = new Patient()
            {
                Name = new List<HumanName>()
                {
                    new HumanName()
                    {
                        Given = new List<string>{"John","James" },
                        Family = "Doe"
                    }
                },
                Gender = AdministrativeGender.Male,
                BirthDate = "1990-01-01",
                Identifier = new List<Identifier>()
                {
                    new Identifier()
                    {
                        Value = "123456790"
                    }
                }
            };
        }
    }
}

You can see that our patient is named “John James Doe” (yes a Patient can have multiple given names in FHIR), and that he is male, born on 01-01-1990, with Patient ID 1234567890 (very easy to remember). Add the following line and run your program:

Console.WriteLine($"Sending patient {patient.Name[0].Given.FirstOrDefault()} {patient.Name[0].Family} ....");

You will see that your output will look like this:

Now that we have our Patient model, we are actually going to send this piece of information to a FHIR server (instead of just printing it to the console. For this, we need to create a FHIR client, and let the client create a new Patient resource (our patient) on the FHIR Test server. In our case we are going to use Firely test server, which you can reach on http://server.fire.ly. The code to make this happen is very simple:

var client = new FhirClient("http://server.fire.ly");
client.Create(patient);

That’s it, the FHIR Client will make sure all http headers are correct, and will transform our content to correct format (xml or json for FHIR), and send the data to the FHIR server. Now we want to check if the patient was actually created. For that, we are going to check if the server send the proper response code. In this case, we want check if server returns Http response code 201, which means “Created”. So we are adding an extra line to our code:

Console.WriteLine($"Result: {client.LastResult.Status}");

This code prints out the status code of the last result our FHIR client received from the FHIR server. When you’ve done everything right so far, the output of your program will look like this:

Step 4 – Retrieving patient data from a server

A FHIR Client is not only able to send data from a FHIR server, but also retrieve data. This can be done by fetching a specific FHIR resource, but you can also use FHIR’s search mechanism to query the server and retrieve all resources that conform to your specific search criteria. So, let’s go ahead and search for all patients named “John”. We are going to re-use the client we created earlier and add a single line for our search query:

var searchResult = client.Search("Patient",new string[] { "name=John" });

The client will search for all Patient resources (first parameter) named “John” (second parameter). You see that the second parameter of this function contains the search criteria, which is an array of strings. This is because you can add multiple criteria to a single search to be more specific.

The result of a search will be a “Bundle”. A Bundle is how FHIR provides a collection of data. Actually, the Bundle not only knows how many records it got from the FHIR server, it also contains the data itself. Each result will be a separate entry in the Bundle. So to display the patient data in our console app, we need to iterate over all Bundle entries:

foreach (var result in searchResult.Entry)
            {
                var pat = result.Resource as Patient;
                Console.WriteLine($"Received patient with {pat.Name[0].Given.FirstOrDefault()}  {pat.Name[0].Family}");
            }

Now when you run your program, your output should look something like this:

You see that we not only retrieve all the John Doe’s we just sent to the server, but also a couple of patients named John Dorian who are apparently also on the test server. Note that these results are different for each person since this is a public FHIR test server in which everyone can create and delete data.

Congratulations! You just made your first FHIR client that can send and retrieve patient data from a FHIR server based on custom search criteria.

Need something more advanced?

This is obviously not code you can use in production environments. There are many more factors needed to create a production-ready FHIR client, but this is a good way to get a little bit more familiar with how FHIR works and to see how easy it is to use the Firely .NET SDK.

If you want to use the FHIR client in more advanced situations you can find the documentation you need right here: https://docs.fire.ly/projects/Firely-NET-SDK/client.html. You can also check out our FHIR software products on our website.

Have fun with FHIR!

Marten