FHIR® tutorials

Patient resource

This tutorial is designed for FHIR beginners wishing to become familiarised with the basics of FHIR. In this tutorial, we will walk through the basic CRUD operations. CRUD stands for Create, Read, Update & Delete. These are the four main actions that you will use to interact with the FHIR resources within a FHIR server. Understanding these four operations is essential to working with any RESTful service which a FHIR server is an implementation of. REST stands for 'Representational state transfer' and RESTFul just means a system that conforms to the constraints of REST. You don't need to know any more about REST at this stage for the tutorial but if you want more on REST take a look at this page, Representational state transfer (REST).

Step 1: Setup a Http post client

The simplest way to retrieve and send FHIR resources to and from a FHIR server is to use a Http post client. This tutorial will use Postman. Postman can be installed as a Chrome browser extension or as a Mac App. You could use any of a number of post clients but the tutorial will assume you are using Postman.

What is a post client? It is a tool that allows you to talk to servers using Hypertext Transfer Protocol (HTTP), the protocol the internet works on. When you use an internet browser the browser is converting your clicks and text into HTTP to send to the web server and the server returns content, your web page, back via HTTP. The browser then interprets the content as a web page and displays it on screen. When we work with FHIR the content is not a web page but rather XML or JSON. Our web browser is not very good at displaying raw XML or JSON so we need a HTTP client so that we can talk in HTTP and view the XML or JSON returned.

Head over to POSTMAN via the link and install Postman now if you have not already done so. You don't need an account to get Postman just download the application.

Once you are done you will have a Postman client that looks like this:

There are other Http post clients that could be used like Fiddler so don't feel you have to use Postman.


Step 2: Getting your first resource from a FHIR server

So the first thing we are going to cover is how you go about getting a FHIR resource from a FHIR server. Of course, before you can get a resource someone had to create one on the server. Luckily for you, this web page can do that for you. The button below will upload a FHIR Patient resource to a FHIR server for you and the tutorial will continue to explain how to retrieve that resource using the post client.

So before we move on click the button below to upload a FHIR Patient resource to the FHIR server. This action will give you a resource to play with independent of the other participants. To do this, all you need to do is hit the button below. Click the button now.

You FHIR patient resource is: ....Click the button for this to refresh!

So you have your own FHIR resource in the FHIR server and a post client to send and retrieve resources with. There are many publicly available FHIR servers for testing on the internet and a full list can be found here. For this tutorial we are going to be using the server found at the following address:

[Service Root URL]

The address above is called the 'Service Root URL' and it is from here that all further request to this server will begin. But of course, we need to further tell the server which resource type we are interested in. This is the next part of the URL. For this tutorial, we are dealing with Patient resources so we will extend the 'Service Root URL' by appending the resource type we are looking for. Take note that all resources begin with a capital letter: e.g. Patient.

[Service Root URL]/Patient

We also need to tell the server which particular Patient resource we want. Generally, you would want to use a Patient's Medical Record Number (MRN), name or other identifiers and we will cover that later in searching. For now we are going to use the resource id to locate our patient. We will also cover more about resource ids a bit later. For now, let's just add the following resource id to our URL we are constructing:

[Service Root URL]/Patient/[id]

We're almost ready to get our resource from the FHIR server but there is one last part we need to cover. We need to understand a little bit about content negotiation. Don't worry, there is not much to it. FHIR resources can be expressed in either JSON or XML, these are just two different ways that we can format a resource's data. Before we talk to our server we need to agree on which format we are going to talk in. To tell the server what format we want to be returned we pass it the Accept property and it needs to be equal to either application/fhir+xml or application/fhir+json. This is something we need to configure in our Http post client Postman. In Postman go to the Header tab and add the following property: Accept application/fhir+xml, as seen in this screenshot.

Ok, we're done. All you need to do is paste the full URL we constructed into the Postman's URL box, ensure the call type is set to GET and hit the Send button. See this screenshot if you need help.

You should have received your first FHIR Patient resource back from the server in an XML format. Well done!

Try changing the Accept property to application/fhir+json hit Send again. You will receive the same resource content although now in a JSON format. Make sure you set it back to application/fhir+xml when your done as the rest of this tutorial will be using the XML format.

Step 3: Updating your resource in the FHIR server

So now you know how to get a resource from the FHIR server. Next, we are going to update an existing resource on the FHIR server. Let's pretend the patient's name was entered incorrectly and it's your job to fix it up. We are just going to use the same resource you retrieved from Step 2: Getting your first resource from a server.

In Postman, you first need to set the call type to PUT, then click the Body tab. Make sure you are clicking the right Body tab as there are two. The Body tab at the bottom is where resources returned by the FHIR server are seen, as in Step 1. The Body tab at the top, just under the URL box, is where we place resources to send to the server. You need to click the Body tab at the top. You will also need to click the radio button labelled raw to allow the Body's text box to be seen. Take a look at this screenshot for help.

Now go ahead and copy the Patient resource we received from the server from the bottom Body section to the top Body section and then in the top section edit the patient's given name and surname to your name. Don't worry, our PAS team is too busy with duplicate patient merging to notice.

With your edits made, it's time to update. But before we do that, we need to cover the last part of 'content negotiation'. In the GET example, we used the Accept property to tell the server the format (XML or JSON) we wanted to be returned by the server. This time, it is us sending content to the server by way of our Patient resource. In this case, we need to tell the server what format the content we are sending is in. To do this we return to the Header tab and use the Content-Type property, and as before we need to set it as either application/fhir+xml or application/fhir+json. But of course, it needs to match the actual content we are sending. So if your Patient resources is in a XML format then use application/fhir+xml or if it is JSON use application/fhir+json. Here is a screenshot of it being set to XML.

Notice that the Accept property is still set from the last GET calls we made. This is fine and actually desired, as long as it is still set to the content type you want to be returned. Now that these two properties are set Postman will remember them for our session, so no need to keep setting them; unless you want to change between XML and JSON. From here forward the exercise will just assume you have these two properties set and will not instruct you to set them again. Furthermore, our exercises will all be done in XML.

Accept: application/fhir+xml or application/fhir+json {format to be returned from the server}
Content-Type: application/fhir+xml or application/fhir+json {format being given to the server}

So now it's time to hit Send which will update the Patient resource on the FHIR server.

Once you have updated, try doing a GET, as in Step 3, to see if your resource was updated. If you compare the versionId within the resource you will see it increased by one.

Step 4: Adding a new resource to the FHIR server

You should now know how to get a resource from a FHIR server and how to update that resource. Now we are going to look at adding a new resource to a FHIR server. Perhaps we have a brand new patient to enter into our system. In the previous 'Step 3: Updating your resource in the FHIR server' we used the call type of PUT to update a resource. These call types are known as HTTP verbs. The most commonly used verbs for FHIR are:

  • GET: Used to retrieve known existing resources and requires a resource id or search parameters to identify the resource or resources required.

  • PUT: Used to update existing resources and always requires a resource id identifying the resource being updated. It can also add a new resource if no resource is found for the id given. In this case, some servers may discard the id and assign their own new id when adding the new resource.

  • POST: Used to add new resources, there must not be an id in the URL or the resource's content. The server will assign its own id to the resource

  • DELETE: Used to remove an existing resource from the server and always requires a resource id to identify the resource being removed. Most servers keep a history of the resource so you can still retrieve the removed resources using the history interaction, we will cover this later.

Let's take our same Patient resource as used in Steps 2 & 3, as our template for the new patient, change it a little, and submit it to the FHIR server as a brand new resource. The first thing to do is change the verb in Postman to be POST and then copy in your new Patient resource into the body section at the top of Postman.

Now we need to edit both the resource and the URL to perform an add. For the URL we need only the 'Service Root' and the resource type, which for this example is Patient as seen below:

[Service Root URL]/Patient

That is the URL done, now for the resource itself. Near the very top of the resource, you will see an id element with an attribute of value which is equal to the id of the resource we copied. This is the resource id and as we are creating a brand new resource we need to remove this whole element. If we don't the server will return a 400 Bad Request error. Feel free to hit Send before you remove it to see this error in action: don't worry, the server won't catch on fire.

So after hitting Send with the id element removed you should be returned the entire resource and a status of 201 Created. If you inspect the returned resource's id element you will find that the server has assigned a new id value, this is now the FHIR servers assigned id for your resource. It's also worth noting the versionId in the meta element, this should be set to '1' as this is the very first version of this resource.

Now you know how to add new resources, the same process works for all resources: you just need change the resource type on the end of the URL.

Step 5: Deleting a resource from the FHIR server

This one's easy, set the Http verb to DELETE and use the 'Service Root' appended with the resource type you wish to remove e.g. 'Patient' and append to that the resource id of the resource you want to remove. So if you had a Patient resource with an id of '123456' then this URL would remove that resource is:

[Service Root URL]/Patient/123456

But before you delete a resource let's think about what happens on the server. Most, but not all FHIR servers support resource history. This means that every update you make to a resource is kept on the server and each update increments a version number. This version number is known as the versionId. When you delete a resource the server treats this action as just another update, yet this update marks the resource as deleted and you will no longer find the resource when doing a normal GET call. But you can retrieve the deleted resource by its versionId. So to explain this a bit better, consider the operations in order below:

  1. Patient resource, added via a POST {this is versionId = 1}
  2. Patient resource, updated via a PUT {this is versionId = 2}
  3. Patient resource, deleted via a DELETE {this is versionId = 3}
  4. Patient resource, attempted to retrieve by resource id via a GET {no resource will be found}
  5. Patient resource, attempted to retrieve by resource id and _history/2 via a GET {resource will be found as updated in step 2}
  6. Patient resource, as retrieve in step 5, added via a POST {this is versionId = 4}

The key point here is that deleting a resource is also considered a version update.

So let's now go ahead and delete our original Patient resource. Using the URL below, setting the Http verb to DELETE and hitting Send.

[Service Root URL]/Patient/[id]

You should receive back a 204 No Content return code which indicates the resource was successfully removed.

Following this you can then retrieve the same resource back again using the _history/[version number you require]. Let's try and retrieve versionId=1 using the URL as below, and the Http verb of GET.

[Service Root URL]/Patient/[id]/_history/1

Now you can delete resources and retrieve historical versions of resources, well done!