Understanding FHIR Fundamentals: Interacting with FHIR REST APIs

In this blog post, we will explore how to interact with FHIR (Fast Healthcare Interoperability Resources) REST APIs. We will cover the process of posting resources to a FHIR server, retrieving them, and updating existing resources. This guide will utilize the HAPI FHIR server and the Insomnia tool for making HTTP requests.

FHIR is a standard for exchanging healthcare information electronically. HL7 provides a list of publicly available FHIR servers, which can be accessed through their website. For this tutorial, we will use the HAPI FHIR server, specifically the R4 endpoint.

Setting Up Insomnia for HTTP Requests

To begin, we need to set up Insomnia, a popular tool for making HTTP requests. After opening Insomnia, we will create a new request to interact with the HAPI FHIR server.

Making a Sample GET Request

1. Open Insomnia and create a new request.
2. Set the URL to the base URL of the HAPI FHIR server.
3. Perform a GET request to see the server's response. This will confirm that we can communicate with the server.

Posting a Patient Resource

Next, we will post a patient resource to the server. Since the patient resource does not have an ID initially, the server will generate one for us.

1. Change the request type to POST.
2. Paste the patient resource in JSON format into the request body.
3. Set the endpoint to /Patient.
4. Send the request. The server should respond with a status of 201 Created, along with the generated ID for the patient resource.

Retrieving the Patient Resource

To retrieve the patient resource we just created:

1. Change the request type to GET.
2. Set the URL to include the patient ID (e.g., /Patient/{id}).
3. Send the request. The server should respond with a status of 200 OK and return the patient resource.

Creating an Observation for the Patient

Now that we have a patient resource, we can create an observation for that patient.

1. Change the request type to POST.
2. Set the endpoint to /Observation.
3. Prepare the observation resource in JSON format, ensuring to reference the patient ID.
4. Send the request. The server will confirm the observation resource has been posted successfully.

Updating an Existing Resource

If we need to correct an observation, we can update it using the PUT method. Here’s how:

1. Retrieve the observation ID from previous requests.
2. Change the request type to PUT.
3. Set the URL to include the observation ID (e.g., /Observation/{id}).
4. Include the updated observation data in the request body, ensuring to specify the correct ID in both the URL and the JSON.
5. Send the request. The server should confirm that the resource has been updated.

Viewing Resource History

To view the history of changes made to the observation resource:

1. Use the URL with the _history parameter (e.g., /Observation/{id}/_history).
2. Send the request to see the version history of the observation, including previous values and statuses.

Understanding FHIR Operations

In summary, we have learned four key operations when interacting with a FHIR server:

• GET: Retrieve resources.
• POST: Create new resources.
• PUT: Update existing resources.
• DELETE: Remove resources (to be covered in future discussions).

Additionally, we can explore the capabilities of the server by sending an OPTIONS request to the base URL, which will provide us with the supported operations.

Conclusion

In this post, we have covered the basics of interacting with a FHIR server, including how to create, retrieve, and update resources. In the next episode, we will delve into searching for resources and the DELETE operation. Thank you for following along, and feel free to leave any questions in the comments below.