APIs are designed to make data transparent and discoverable. They’re an obvious choice for healthcare professionals, but it does open up certain complications. How do you make healthcare data available and easily shareable across many different platforms without exposing sensitive patient data in the process?

Recently, Health Level 7 Initiative (HL7) rolled out a new standard to help address some of these questions. The Fast Healthcare Interoperability Resources (FHIR) specification standardizes healthcare information for easy electronic sharing. So how can you make sure your APIs are FHIR-compliant?

Luckily, making an FHIR-compliant API isn’t that dissimilar from many existing API guidelines. For REST APIs, standardized metadata and human readability are key components of Roy Fielding’s vision. But let’s dig a little deeper into the specifics of creating APIs for FHIR, to help ensure your data is in accordance with the latest standards and guidelines.

What Is FHIR?

To understand how to make an FHIR API, it helps to have an understanding of the standard itself. FHIR stands for Fast Healthcare Interoperability Resources. It’s a data exchange standard released by HL7, an international non-profit organization for creating standardized electronic information resources founded in 1987.

HL7 has long suffered from complaints around its proprietary TCP-based messaging system as well as inconsistencies in the data standards and formatting. FHIR is the industry’s response to these problems and criticisms.

What FHIR Addresses

The FHIR standard specifies the models for representing healthcare domains, the relationships, and what operations can be performed. FHIR also defines individual components that are allowed under the standard. These are known as Resources. Examples of FHIR Resources include:

• Patient
• Practitioner
• Healthcare Service

FHIR also allows linking to more abstract concepts like diagnostics, which can include Observation or Report, and workflows, such as Schedule, Appointment, or Task.

FHIR doesn’t require HTTP, but it’s strongly implied as a preference. Each type of model is a standalone REST resource, and individual actions are mapped to HTTP actions. An example of an FHIR API request for patient info on Patient id 162656 might look like GET /Patient/162656.

REST Compliance

Thanks to its usage of HTTP verbs and hypermedia links, FHIR ranks as a strong Level 2 according to Leonard Richardson’s REST Maturity Model. The standard is also quite specific on how to implement REST APIs with an entire page on how to implement FHIR-Compliant REST APIs. This includes a detailed style guide. According to their API guidelines, all API requests must adhere to the following format:

VERB [base]/[type]/[id] {?_format=[mime-type]}

Content in [] is mandatory and should be replaced with the assets being requested.

Other concepts outlined in their API guidelines include:

• Resource paths
• Usage of HTTP verbs
• HTTP status codes
• Search query parameters
• Partial updates/patches
• Paging
• Batch operations
• Error format

Thanks to the standardized format of FHIR APIs, there’s already a ton of tooling available which can be used to make your APIs FHIR-compliant.

Tools For Creating FHIR-Compliant APIs

Here are a few tools you can use to create your own FHIR-compliant healthcare APIs. These tools can also give you ideas for configuring your own healthcare services.

HAPI FHIR

HAPI-FHIR is an open-source library for Java. The site even features test servers so you can see FHIR-compliant healthcare APIs in action.

Working with the HAPI FHIR is also a crash course in implementing your own APIs. Their extensive documentation offers detailed guidelines on everything from working with resources to creating child objects to creating FHIR servers.

Simplify.net FHIR Test Server

For some reason, many of the public test servers included on popular lists and roundups are dead. That makes Simplify.net’s FHIR Test Server all that much more useful, as a simple barebones FHIR API server to model your own FHIR-compliant API after. It gives you a clear visual of how to structure and format your own FHIR APIs.

There’s even an FHIR API endpoint where you can try it out for yourself.

Tips For Working With FHIR API

Conceptualize Resources

If you have limited experience with data architecture, FHIR can be daunting. To more easily picture how Resources work under FHIR, think of each Resource as 1 of 145 linked spreadsheets. Using this image, think of individual data fields like Patient Identifier, Name, or Gender as columns for that specific spreadsheet.

Learn HTTP Commands

As we said earlier, FHIR doesn’t demand HTTP, but it’s strongly implied. The FHIR API features a system of Instance, Type, and System interactions, built around the familiar CRUD patterns but with slightly more extensive controls. Examples of HTTP requests using the FHIR API following the prescribed standard include:

• Creating a new resource: POST http://www.xample.com/path/{resourceType}
• Reading the current status of a Resource: GET http://www.xample.com/path/{resourceType}/{id}
• Update an existing Resource: PUT http://www.xample.com/path/{resourceType}/{id}
• Delete a Resource: DELETE http://www.xample.com/path/{resourceType/{id}
• Search a Resource or Resources based on search criteria: SEARCH http://www.xample.com/path/resourceType/?search_parameters
• Retrieve the change history of a Resource or Resources: GET https://www.xample.com/path/{resourceType}/{id}/history

The FHIR API also supports more complex HTTP requests, including Batch/Transaction, Operation, Vread, Patch, and Capabilities.

Extend and Restrict the API

FHIR-compliant APIs can be further customized using the Capability Statement Resource, which lists the REST interactions available on a specific server. The Capabilities statement is the only interaction a server is required to support.

FHIR servers and clients use whatever API calls support their specific use. They can also support additional operations outside of the FHIR operations. A Conformance Resource specifies what Operation Definitions use particular names for an endpoint.

Learn By Example

As we have seen, the FHIR specification is quite deep and layered. For those familiar with working with APIs, the concepts won’t be that revolutionary or difficult to comprehend, but having a concrete example to base your own APIs on will make your life exponentially easier.

FHIR healthcare APIs have become quite prevalent since HP7 first rolled out the standard, so there are plenty of examples for you to choose from. HealthGorillas API is an especially fine example, as well as an excellent example of API documentation.

Final Thoughts On FHIR-Compliant APIs

Recent years have made the need for fast, reliable data handling in the healthcare industry all too obvious. There’s also been an increasing push for data transparency in healthcare for everything from pricing to patient records. After everything we’ve learned from the COVID-19 pandemic, it’s increasingly obvious that APIs will play an increasing role in the global healthcare industry.

Yet, healthcare applications will require a zero-trust approach when adopting APIs. Following the FHIR standard will help ensure that your customers and patients will be safe, secure, and protected when using an electronic transfer format. It’s also likely a matter of time until FHIR or some similar guideline becomes mandatory. Paid FHIR solutions are already starting to proliferate in the digital healthcare sector. Therefore, it’s to both you and your customers’ benefit to learn to encode your own FHIR API requests now — this will help avoid incurring more ongoing expenses that raise the already prohibitively high patient cost.