Getting Started with FHIR REST API
Prerequisites
Installing Postman
Postman is an application that allows users to exercise REST APIs. In this tutorial, we will be using it to create, read, query, update and delete a Patient FHIR Resource.
We recommend installing postman one of two ways:
-
through a package manager, ie for mac
brew cask install postman
-
or from the Postman website
Goals
In this tutorial you will learn how to:
- Create, read, query, update, and delete FHIR Resources using the Helios FHIR Server
- Access the Helios FHIR Server UI
- Create, edit, and delete Users through the Helios FHIR Server User Management tool
- Read and update Helios FHIR Server Configurations
Creating a FHIR Resource and Editing HFS Configurations
-
Open Postman and create a new "Collection". Name the collection whatever you like, we recommend "HFS FHIR API". The default settings are fine.
-
Create a new "Request" using the New button in the upper left corner of the Postman window. Call it "HFS Patient Create" and save it to your new "HFS FHIR API" Collection.
-
Configure your new Request with the following properties:
- Using the HTTP Method dropdown, select POST instead of GET
- Edit the URL bar to be
http://localhost:8181/fhir/Patient
(If you have changed any of your HFS hostname or port settings, this may not be the proper URL) - Add the header "Content-Type": "application/fhir+xml" to the Headers tab
- Select the 'raw' radio button under the Body tab and paste the example Patient XML document into the text field.
Make sure your request matches the screenshots.
-
Click the Send button.
This request will fail with a 401 Unauthorized error! With the Helios FHIR Server, there are multiple ways of solving this. We can provide authorized credentials using Basic authorization, we can whitelist anonymous POSTing to the server, or we can fully turn off Basic authorization fully. For this tutorial, we're going to start by whitelisting the POSTing of data.
-
Open a browser window to
http://localhost:8181/ui
. When prompted, login with the default admin credentials:admin@heliossoftware.com/admin
. -
Click the settings tab in the sidebar.
- Edit the
White Listed HTTP Methods
underSecurity Settings
fromGET
toGET,POST
. For this configuration, HFS uses a comma separated list of HTTP methods. (Possible values areGET
,POST
,PUT
,DELETE
)
-
Return to your Postman window and re-send the request. It will now succeed.
Congratulations! You have created your first FHIR resource in your Helios FHIR Server! Next, lets try to read that Patient back out.
Reading the FHIR Resource
- In the body of the response from the Patient request, you will find an id value. It should be one of the first attributes. Copy this value somewhere safe, we will need it for multiple subsequent steps. (Make sure not to copy the quotation marks and only select the guid value)
-
Save your Postman request. Create a new request using the same method as previous. Name it "HFS Patient Read". Supply the url as
http://localhost:8181/fhir/Patient/<copied-id>
where<copied-id>
is the id saved in the previous step. All other settings can be left as the defaults. -
Click the Send button. This request will succeed without any additional parameters or headers or configuration changes because GET is white listed by default in the HFS.
-
There are other ways to request data from the HFS. We can query for all of the records in the system. Save your Postman request and create a new one that is the same but with a url of
http://localhost:8181/fhir/Patient
. If we execute a GET to the root of Patient, it will query for ALL of the Patient records in the system. -
Click the Send button. This request returns a FHIR Bundle instead of a Patient. A Bundle is a way of compiling multiple resources into one. Look at the
entry
attribute of the response Bundle. You'll note that it is an array, which would accept multiple entries, but that there is only one populated. This is because we have only created one Patient record. -
We can also use FHIR Search Parameters to request data from the system.
- Edit your request URL to be
http://localhost:8181/fhir/Patient?given=Peter
and click Send. You will receive a Bundle as a response with the same Patient. - Try
http://localhost:8181/fhir/Patient?family=Chalmers
. This matches on a different field of the Patient and returns. - We can even combine Search Parameters to do a really specifc query.
Try
http://localhost:8181/fhir/Patient?given=Peter&family=Chalmers
- Edit your request URL to be
Updating a FHIR Resource
-
Next, lets try updating the Patient record. Save your current Postman Request and create a new one. This request should match the POST request with one exception. Instead of POST, the HTTP method should be PUT.
- Make sure to set the "Content-Type": "application/fhir+xml" header
- change the body type to 'raw' and re-paste the example Patient XML from earlier.
- Make sure the HTTP method is PUT not POST
- the URL should be
http://localhost:8181/fhir/Patient/<copied-id>
where<copied-id>
is the id from earlier.
-
Additionally, we need to make a couple new changes:
- In the Authorization tab, select
Basic Auth
from the Type dropdown. Fill in the username/password field withadmin@heliossoftware.com/admin
.
- In the Body tab, we need to replace the default id of
example
with the<copied-id>
. This is required because the HFS rejects update requests that do not have a matching ID in the URL path and the request body.
- In the Body tab, we want to edit the Patient's family name from "Chalmers" to "Parker". This will represent our "updated" data
- In the Authorization tab, select
-
Click Send. The request will succeed.
-
To verify that the record updated, we can query on our new
family
value. Try executing aGET
for the URLhttp://localhost:8181/fhir/Patient?family=Parker
. You will get a Bundle with our updated Patient. Next, try a query on the original valuehttp://localhost:8181/fhir/Patient?family=Chalmers
. You will get an empty Bundle, since no record matches that value anymore!
Deleting a FHIR Resource and Managing Users in HFS
-
Finally, lets create a new Helios FHIR Server user and use that user to delete our Patient record.
-
Navigate back to the Helios FHIR Web UI at
http://localhost:8181/ui
. Your session should still be valid, but if it is not, you may be prompted to log in again. -
Once you are on the Dashboard, click on "Users" in the sidebar.
-
Click the "Add User" button in the upper right corner.
-
You can fill this out however you want, with the caveat that the
Email
field must be a syntactically valid email (it does not have to be a real email) and thePassword
andConfirm Password
fields must match. We recommend you enable all of the roles for ease of use in this tutorial.Note: the username is not editable once the user is created.
-
Click the "Add New User" button at the bottom of the screen.
-
The "Add New User" button redirects you to the User Management page. From here, you can add new users like we just did, as well as delete and edit existing users. Since we added a new user with the
Administrator
, at this point it would be safe to delete the defaultadmin@heliossoftware.com
user, if you wanted to for security reasons. It is not necessary for this tutorial. -
Navigate back to Postman. If you have unsaved changes that you would like to keep, save your current request. Create a new request and name it "FHIR Patient Delete".
- The HTTP Method should be
DELETE
- The URL should be
http://localhost:8181/fhir/Patient/<copied-id>
where the<copied-id>
is the id from earlier. - The Authorization tab should be
Basic Auth
with theusername/password
being the credentials for the user you just created. For example, for these instructions, it would bespiderman@alias.com/1234
.
- The HTTP Method should be
-
Click Send. You will recieve a successful 204. If you want, you can verify that the record is gone by doing:
- a GET to
http://localhost:8181/fhir/Patient/<copied-id>
. This will return a 410 (Gone) because HFS knows it had this record and that it has been deleted. - a GET to
http://localhost:8181/fhir/Patient
. This will return an empty Bundle because there are no Patient records - a GET to
http://localhost:8181/fhir/Patient?family=Parker
. This will return an empty Bundle because there are no Patient records that match (or that exist)
- a GET to
Finish and Next Steps
-
This concludes the Helios FHIR Server Getting Started with FHIR REST API! Congratulations! You should now feel comfortable with:
- Creating, Reading, Querying, Updating and Deleting data into and from the Helios FHIR Server
- Accessing the Helios FHIR Server UI
- Creating, Editing and Deleting Users through the Helios FHIR Server User Management tool
- Reading and Updating Helios FHIR Server configurations
For any followup questions please contact
steve@heliossoftware.com
orharrison@heliossoftware.com