Helios FHIR Server Getting Started with FHIR REST API

Prerequisites

  1. Postman

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:

  1. through a package manager, ie for mac
    $ brew cask install postman
  2. 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

  1. Open Postman and create a new "Collection". Name the collection whatever you like, we recommend "HFS FHIR API". The default settings are fine.

    Postman 'New Collection' Screenshot
  2. 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.

    Postman 'New Request' Screenshot
  3. Configure your new Request with the following properties:

    1. Using the HTTP Method dropdown, select POST instead of GET
    2. 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)
    3. Add the header "Content-Type": "application/fhir+xml" to the Headers tab
    4. Select the 'raw' radio button under the Body tab and paste the example Patient XML document into the text field.
    Postman 'Configured Request' ScreenshotPostman 'Configured Request' Screenshot

    Make sure your request matches the screenshots.

  4. 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.

  5. Open a browser window to http://localhost:8181/ui. When prompted, login with the default admin credentials: admin@heliossoftware.com/admin.

  6. Click the settings tab in the sidebar.

    HFS Dashboard Screenshot
  7. Edit the White Listed HTTP Methods under Security Settings from GET to GET,POST. For this configuration, HFS uses a comma separated list of HTTP methods. (Possible values are GET, POST, PUT, DELETE)

    HFS Settings Screenshot
  8. 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

  1. 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)

    Postman Response Body
  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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

Updating a FHIR Resource

  1. 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.
  2. 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 with admin@heliossoftware.com/admin.Postman Basic Auth
    • 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.Postman Edited ID
    • In the Body tab, we want to edit the Patient's family name from "Chalmers" to "Parker". This will represent our "updated" dataPostman Edited Family
  3. Click Send. The request will succeed.

  4. To verify that the record updated, we can query on our new family value. Try executing a GET for the URL http://localhost:8181/fhir/Patient?family=Parker. You will get a Bundle with our updated Patient. Next, try a query on the original value http://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

  1. Finally, lets create a new Helios FHIR Server user and use that user to delete our Patient record.

  2. 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.

  3. Once you are on the Dashboard, click on "Users" in the sidebar.

  4. Click the "Add User" button in the upper right corner.

  5. 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 the Password and Confirm 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.

    HFS Dashboard New User
  6. Click the "Add New User" button at the bottom of the screen.

  7. 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 default admin@heliossoftware.com user, if you wanted to for security reasons. It is not necessary for this tutorial.

  8. 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 the username/password being the credentials for the user you just created. For example, for these instructions, it would be spiderman@alias.com/1234.Postman Delete Request
  9. 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)

Finish and Next Steps

  1. 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 or harrison@heliossoftware.com