Your First Interactions with Your FHIR Server

In my previous blog post we downloaded, installed and fired up an instance of Firely Server running on your own Windows PC. Now that was a pretty cool thing to do. However FHIR servers are social creatures and letting it sit around idly will make it unhappy. So let’s spend some time with it and kick start your first interactions with your FHIR server!

0. Setting the stage

In this post we will be interacting with Firely Server, so the first thing we need … is Firely Server. If you haven’t done so already you can work your way through my previous blog post in order to install Firely Server on your own PC. However if you are just interested in the interaction part you can use our own public Firely Server on https://server.fire.ly.

In this blog post, let’s assume that you are using your own Firely Server and that it does not contain any data yet. If you have installed it but also posted some resources you can easily reset the database using the reset operation.

For interacting with Firely Server we will use the Postman app which can be downloaded for free from https://www.postman.com/downloads/. As an alternative you can also use the web version mentioned on the download page but, in order to do this, you will have to create an account. In this blog I will use the app since I find it more convenient to use.

Throughout this blog post you will find links to either the Firely Server documentation or the FHIR specification. These links provide more in depth information on the current topic. If you want to take a deeper dive, you can follow them but this is not needed for successfully completing this blog post. Now let’s get started!

1. Configuring Postman

When you start Postman you will see a dialog similar to the one below. Start by clicking on the four areas indicated in the image with a green circle to create a larger workspace and open a pane to work in.

The Postman window is roughly divided in a top and a bottom part. The top part deals with the request and the bottom with the response.

The request is what we send to the FHIR server and the response is what the server sends back to us. Both the request and response contain things such as a header and a body. Please pay attention to this in the next steps mentioned below e.g. whether the body is in the request or response part of Postman.

There are a few things we need to configure in order for all of the following steps to succeed. First we need to tell Postman where our Firely Server instance can be found, the so called service base URL. Next to GET enter the following URL:

http://localhost:4080

If you decide to use the public Firely Server instance you need to replace the URL above with:

https://server.fire.ly

For the rest of this post I will use the first URL. This URL by itself won’t do anything useful but in the following steps we will append to it.

GET is called a HTTP verb that you can and should change depending on the type of request you are sending, e.g. GET, POST or PUT. From now on, I will place the relevant verb next to the URL. So in the example above it would be:

GET	http://localhost:4080

When sending a request to the FHIR server we need to tell it how the data in the body we provide is formatted as well as the format we would like to receive data back from the server. We do that by setting the MIME type. Click on Headers and add the following two key/value pairs, indicating that we will be sending FHIR data formatted as JSON and that we would like to receive data in the same format.

Key	Value
Accept	application/fhir+json
Content-Type	application/fhir+json

Now we are ready to start sending requests to the server and receiving responses.

2. Creating your first Patient resources

Each resource type has its own manager that can be accessed by appending the type name to the service base URL. Since we will be working with Patient resources in this blog post we need to change the request URL to the following:

GET	http://localhost:4080/Patient

When we send this request we perform a Patient search on the server with no search criteria. As a result, the FHIR server will return all Patient resources to us. The results will be wrapped in a resource bundle.

There is usually quite a bit of security involved to make sure we only see patient data that we have access to. For the sake of simplicity we won’t use any security measures in this blog post. So we can now press Send without any hesitation.

You have just fired off your first request to Firely Server! Let’s look at the response from the FHIR server.

Encircled in green you see the HTTP status code returned which is 200 indicating that the request was processed without any issues. The Body of the response contains a resource of type Bundle. The total of 0 indicates that the Bundle contains no resources, which is expected from querying a freshly installed Firely Server instance. If you run this query against the public Firely Server you will probably get back a number of Patient resources.

Let’s create a Patient resource. Change the URL and paste the contents below in the request body:

POST	http://localhost:4080/Patient

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Curie"  
    }    
  ]
}

The status code of 201 indicates that the resource was successfully created. The created resource itself is returned as part of the response body. As you can see additional information was added by the server: a unique id for this Patient resource, a version id as well as a date and time showing when the resource was last updated.

The id you received will be different. Please copy and paste your id since we will be using it in the next steps. Wherever I use my id (12e2e0ed-fb95-4f5e-97c5-251aff1e369d) you need to replace it with yours.

Let’s add a second Patient resource, no further help here, you can do this. ?

POST	http://localhost:4080/Patient

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Franklin",
      "given": "Rosalind"  
    }    
  ]
}

Let’s finish this step by retrieving all Patient resources once again and check that this time the bundle contains not 0 but 2 resources. Update the URL to match the one below and press Send:

GET	http://localhost:4080/Patient

Again, we received a bundle. Only this time it contains our two resources!

3. Retrieving your Patient resources

I will now show you two ways to retrieve a specific Patient resource by either using a read or a search.

Read retrieves a resource of a given type, Patient in this case, matching a given id. The URL for our first resource looks like this:

GET	http://localhost:4080/Patient/12e2e0ed-fb95-4f5e-97c5-251aff1e369d

Paste the URL in the Postman request URL, change the id to match yours and press Send.

A search allows you to retrieve resources using one or more search parameters. There are common search parameters that apply to all resources and additional search parameters specific to a resource type, e.g. Patient search parameters.

Let’s say I forgot to write down the id of the second Patient resource I created, but I do remember the last name which was Franklin. Since one of the search parameters for Patient is name we should be able to retrieve the resource using the URL below. Go ahead and give it a try:

GET	http://localhost:4080/Patient?name=Franklin

Success again! Now do notice that this time the response body does not contain a Patient resource, but a Bundle. The reason for this is that a search can return 0 (no match), 1 (as in this case) or more resources (e.g. all family members) and these all fit nicely in a Bundle.

4. Updating your Patient resource

When I created the first resource I omitted the given name, Marie. Let’s add that to the resource using an update.

It’s important to remember that an update overwrites the current resource on the FHIR server. If we would only add the first name and omit the last name, then the last name would be lost. Furthermore when performing an update you need to make sure that the id in the URL matches that of the id in request body. Here are the URL and the request body:

PUT	http://localhost:4080/Patient/12e2e0ed-fb95-4f5e-97c5-251aff1e369d

{
    "resourceType": "Patient",
    "id": "12e2e0ed-fb95-4f5e-97c5-251aff1e369d",
    "name": [
        {
            "family": "Curie",
            "given": "Marie"
        }
    ]  
}

We should get a 200 status code and the response body should contain the updated resource with both the last and first name. If not make sure that you replaced the id in both the URL and the request body with your own id and that you used PUT.

5. Wrapping up

And with that we have come to the end of this blog post. You have created two Patient resources, retrieved them all, retrieved them individually using two different methods and you have added missing information to an existing Patient resource. Congratulations on a job well done!

Of course this is just the tip of the iceberg, but hopefully you now feel more confident in interacting with Firely Server. All the nitty gritty details are in the FHIR specification which I have linked to throughout this post. However there is still a large gap between this blog post and the FHIR spec. If you want to make it easy on yourself consider signing up to one of our FHIR training courses or workshops.

I hope you had as much fun working your way through this blog post as I had writing it. As usual, feedback is greatly appreciated. Feel free to leave a comment below if you have a request for a follow up blog post. We would love to hear it!