FHIR Programming using Java and HAPI FHIR Server

FHIR Programming using Java and HAPI FHIR Server - Setting Up Your Environment

May 16, 2025

Introduction

Welcome to the second article in my series on FHIR Programming using Java and HAPI FHIR Server. In this article, I will guide you through setting up your development environment, so you can start creating, reading, updating, and deleting FHIR resources. Before proceeding with this tutorial, it is highly recommended that you read my introductory article on FHIR standard which provides essential background information and sets the foundation for the concepts and steps covered in this tutorial.

The FHIR standard has gained significant popularity in the healthcare industry, and for Java programmers, there is excellent support available to leverage this standard. With the HAPI FHIR library, developers can easily create, read, update, and delete FHIR resources using familiar Java programming paradigms. The library provides a comprehensive set of classes and methods that abstract the complexities of working with FHIR, allowing developers to focus on building robust and scalable healthcare applications. Additionally, the integration of FHIR with HAPI FHIR Server further enhances the capabilities for Java programmers, enabling seamless connectivity to a FHIR server and leveraging the power of open-source solutions. Whether it's building interoperable healthcare systems or developing innovative healthcare solutions, the combination of FHIR and Java offers a powerful and efficient platform for developers to deliver high-quality healthcare applications.

Understanding FHIR Fundamentals

Before diving into the technical setup, it's essential to understand some fundamental FHIR concepts that will help you work more effectively with the standard.

FHIR Versioning

FHIR has evolved through several versions, each building upon the previous one with improvements and new features:

DSTU1 (Draft Standard for Trial Use 1) - The initial release, now considered obsolete.
DSTU2 - Introduced significant improvements and was widely adopted for early implementations.
STU3 (Standard for Trial Use 3) - Added maturity model ratings for resources and refined many specifications.
R4 (Release 4) - The first normative release with guaranteed backward compatibility for core resources. This is the version we use in this tutorial series and is currently the most widely implemented.
R5 (Release 5) - The latest version with additional resources and refinements, though R4 remains the most commonly deployed.

When selecting a FHIR version, consider what your trading partners support, regulatory requirements in your jurisdiction, and the maturity of available tooling. R4 is generally the safest choice for new implementations due to its normative status and broad adoption.

REST Fundamentals in FHIR

FHIR is built on RESTful principles, using standard HTTP methods to interact with resources:

GET - Read a resource or search for resources
POST - Create a new resource (server assigns the ID)
PUT - Update an existing resource (or create with client-specified ID)
DELETE - Remove a resource
PATCH - Partially update a resource

Each FHIR resource has a logical URL structure: [base]/[resourceType]/[id]. For example, http://server.com/fhir/Patient/123 refers to a Patient resource with ID "123". This RESTful design makes FHIR intuitive for developers familiar with web APIs and enables easy integration with existing web infrastructure.

FHIR Context and Client Architecture

The HAPI FHIR library uses a context-based architecture pattern that provides several important benefits:

FhirContext - This is a heavyweight, thread-safe object that should be created once and reused throughout your application. It contains the metadata and parsers for a specific FHIR version. Creating a FhirContext is expensive (it scans and initializes all resource definitions), so reusing it improves performance significantly.
IGenericClient - Created from the FhirContext, this is the main interface for interacting with a FHIR server. It provides fluent APIs for CRUD operations, searches, and transactions.
Interceptors - The client supports interceptors that can modify requests and responses, useful for logging, authentication, and custom headers.

This separation of concerns allows the context to be optimized for a specific FHIR version while the client handles the HTTP communication details.

Server Capability Statements

Every FHIR server publishes a CapabilityStatement (previously called "Conformance" in earlier FHIR versions) that describes what the server can do. This metadata document is crucial for client applications because it declares:

Supported Resources - Which FHIR resources the server supports (Patient, Observation, etc.)
Supported Interactions - What operations are available for each resource (read, search, create, update, delete)
Search Parameters - Which search parameters are implemented for each resource
Security Requirements - Authentication and authorization mechanisms required
Supported Profiles - Any implementation guides or profiles the server conforms to

Clients can retrieve this statement by making a GET request to [base]/metadata. Programmatically checking the CapabilityStatement before performing operations helps build robust applications that gracefully handle server limitations.

Types of FHIR Servers

Understanding the different types of FHIR servers helps you choose the right one for your needs:

Reference/Test Servers - Public servers like HAPI's test server (http://hapi.fhir.org/baseR4) are meant for learning, testing, and development. They typically have no authentication, limited data retention, and should never be used for real patient data.
Development Servers - Local or cloud-hosted servers for your development team. Often run via Docker for easy setup and teardown.
Production Servers - Enterprise-grade servers with proper security, backup, high availability, and compliance certifications (HIPAA, GDPR, etc.). Examples include Azure API for FHIR, Google Cloud Healthcare API, and AWS HealthLake.
Facade Servers - Servers that don't store data themselves but translate FHIR requests to underlying legacy systems, providing a FHIR interface to existing data.

Prerequisites

Before we get started, ensure you have the following installed:

Download the latest version of Java Development Kit (JDK) from the official Java website.
Download and install Apache Maven from the official Maven website.
Download and install an Integrated Development Environment (IDE) such as IntelliJ IDEA or Eclipse.
You can find all the code demonstrated in this tutorial on GitHub here

“The goal of interoperability is structural and semantic interoperability. To achieve this goal, we need several standards grouped into three categories: lower level standards as technical groundwork, content standards like FHIR that provide structure, and terminology standards like SNOMED CT, ICD-10, or LOINC to complete the semantic meaning.” ~ Health Interoperability Principles

Step 1 of 5: Create a New Java Project

Apache Maven is a powerful build automation tool used primarily for Java projects. It simplifies the process of managing project dependencies, building, and deploying Java applications. Maven uses a Project Object Model (POM) file to define project structure, dependencies, and build configurations. With Maven, you can easily manage external libraries, compile your code, run tests, and package your application into a deployable format. Maven also provides a standardized project structure, making it easier to organize and maintain your codebase. Whether you are working on a small personal project or a large enterprise application, Maven empowers you to streamline your development workflow and ensures consistent and reproducible builds.

First, create a new Maven project. Open your terminal or command prompt and run the following commands:

mvn archetype:generate -DgroupId=com.saravanansubramanian.fhir -DartifactId=FhirJavaTutorial -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
cd FhirJavaTutorial

This will create a new Maven project named FhirJavaTutorial.

Step 2 of 5: Install HAPI FHIR Library

About the Library

The HAPI FHIR library is a comprehensive Java library specifically designed for working with the FHIR (Fast Healthcare Interoperability Resources) standard. It provides a set of intuitive and easy-to-use classes and methods that abstract the complexities of working with FHIR, allowing developers to focus on building robust and scalable healthcare applications. With the HAPI FHIR library, developers can easily create, read, update, and delete FHIR resources using familiar Java programming paradigms. This library offers a powerful and efficient platform for developers to deliver high-quality healthcare applications by leveraging open-source solutions. It enables seamless connectivity to HAPI FHIR Server, which provides a scalable and secure platform for storing and managing FHIR resources. By using the HAPI FHIR library, developers can build interoperable healthcare systems and innovative healthcare solutions.

The HAPI FHIR library helps solve a variety of problems faced by Java programmers in the healthcare industry. Firstly, it simplifies the process of working with the FHIR standard, which can be complex and time-consuming. The library abstracts the complexities of FHIR, providing a set of intuitive and easy-to-use classes and methods that streamline the development process. This allows developers to focus on building the core functionality of their healthcare applications, rather than getting bogged down in the intricacies of FHIR implementation.

Secondly, the HAPI FHIR library enhances the capabilities of Java programmers by integrating FHIR with open-source solutions. This integration enables seamless connectivity to HAPI FHIR Server, which provides a scalable and secure platform for storing and managing FHIR resources. By leveraging the power of open-source solutions, developers can build robust and scalable healthcare applications that can handle large volumes of data and provide real-time access to patient information.

In summary, the HAPI FHIR library is a valuable tool for Java programmers in the healthcare industry. It simplifies the process of working with the FHIR standard and enhances the capabilities of Java programmers by integrating FHIR with open-source solutions. By using the HAPI FHIR library, developers can build high-quality healthcare applications that are interoperable, scalable, and secure.

Packages in Java

In Java, packages are a way to organize and group related classes and interfaces. A package is a namespace that allows you to avoid naming conflicts and logically organize your code. By using packages, you can group classes that are related to a specific functionality or module, making your code more modular and maintainable. Packages also provide access control, allowing you to restrict access to certain classes and methods, thus enhancing the security and encapsulation of your code. In a Maven project, dependencies are managed through the `pom.xml` file. This file defines the project structure, dependencies, and build configurations. By adding the HAPI FHIR library dependency to your `pom.xml` file, you gain access to a comprehensive set of classes and methods that abstract the complexities of working with FHIR. This enables you to easily create, read, update, and delete FHIR resources using familiar Java programming paradigms. Adding packages and managing dependencies through Maven is an essential step in leveraging existing libraries and accelerating your development process. It allows you to build upon the work of others and focus on building the core functionality of your application, rather than reinventing the wheel.

Next, add the HAPI FHIR library to your project. Open your `pom.xml` file and add the following dependencies:

<dependencies>
    <!-- HAPI FHIR Core -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-base</artifactId>
        <version>6.6.0</version>
    </dependency>
    
    <!-- HAPI FHIR R4 Structures -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-structures-r4</artifactId>
        <version>6.6.0</version>
    </dependency>
    
    <!-- HAPI FHIR Client -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-client</artifactId>
        <version>6.6.0</version>
    </dependency>
    
    <!-- HAPI FHIR Validation Resources -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-validation-resources-r4</artifactId>
        <version>6.6.0</version>
    </dependency>
    
    <!-- For logging -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.7</version>
    </dependency>
</dependencies>

Step 3 of 5: Set Up HAPI FHIR Server

HAPI FHIR Server is an excellent choice for learning and using in this tutorial due to its numerous advantages and features. Firstly, HAPI FHIR Server provides a scalable and secure platform for storing and managing FHIR resources. This means that developers can easily handle large volumes of data and ensure the privacy and security of patient information. With HAPI's robust infrastructure and advanced security measures, developers can focus on building their healthcare applications without worrying about the underlying infrastructure.

Secondly, HAPI FHIR Server seamlessly integrates with other open-source solutions, allowing developers to leverage the power of community-driven development. This integration enables developers to take advantage of features such as automatic scaling, high availability, and real-time data processing. By utilizing open-source solutions, developers can build highly performant and efficient healthcare applications that can handle the demands of modern healthcare systems.

In addition, HAPI FHIR Server offers extensive documentation and resources, making it easy for developers to get started and learn the intricacies of FHIR programming. The community provides comprehensive documentation, tutorials, and sample code that cover various aspects of FHIR development using HAPI FHIR Server. This wealth of resources ensures that developers have the necessary guidance and support to successfully build their healthcare applications.

Overall, HAPI FHIR Server is a powerful and reliable platform for learning and using FHIR in this tutorial. Its scalability, security, integration with open-source solutions, and extensive documentation make it an ideal choice for developers looking to build robust and innovative healthcare applications.

Set Up a HAPI FHIR Server

You can download the HAPI FHIR Server from the official HAPI FHIR website.
Alternatively, use Docker to run a pre-configured HAPI FHIR server with this command:
```
docker run -p 8080:8080 hapiproject/hapi:latest
```
Note the Base URL of your HAPI FHIR server. If running locally via Docker, it will be: http://localhost:8080/fhir.

“There are perhaps no days of our childhood we lived so fully as those we spent with a favorite book.” ~ Marcel Proust

Step 4 of 5: Connect to HAPI FHIR Server from Java

When connecting to a HAPI FHIR server behind the scenes, several steps are involved. First, you need to provide the base URL of your FHIR server. This URL acts as the endpoint for your application to communicate with the server. Once the base URL is provided, a new instance of the `FhirContext` class is created. This context is responsible for establishing the connection and handling the communication with the FHIR server. Internally, the `FhirContext` uses the HTTP protocol to send requests and receive responses from the server. It encapsulates the necessary logic to handle authentication, serialization, and deserialization of FHIR resources. When the connection is established, the context sends a request to the server, typically a `GET` request to retrieve information or a `POST` request to create a new resource. The server processes the request and returns a response to the context. The response contains the requested data or an acknowledgment of the successful creation of a resource. The context then parses the response and provides the necessary data to the application.

Behind the scenes, the HAPI FHIR server handles various tasks, such as validating the request, retrieving or storing data in the underlying storage system, and enforcing security and access control policies. It ensures the integrity and confidentiality of the data and provides a reliable and scalable platform for managing FHIR resources. In summary, when connecting to a HAPI FHIR server, the `FhirContext` establishes a connection, sends requests to the server, and receives responses. The server processes the requests and handles the necessary operations, ensuring the secure and efficient management of FHIR resources.

Open your `App.java` file and update it as follows:

package com.saravanansubramanian.fhir;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.api.IGenericClient;
import ca.uhn.fhir.rest.client.interceptor.LoggingInterceptor;
import org.hl7.fhir.r4.model.CapabilityStatement;

public class App {
    public static void main(String[] args) {
        // Create a FHIR context - using R4 as the FHIR version
        FhirContext ctx = FhirContext.forR4();
        
        // Create a client to connect to the FHIR server
        String serverBaseUrl = "http://localhost:8080/fhir";
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);
        
        // Add a logging interceptor to view the HTTP traffic
        LoggingInterceptor loggingInterceptor = new LoggingInterceptor();
        loggingInterceptor.setLogRequestBody(true);
        loggingInterceptor.setLogResponseBody(true);
        client.registerInterceptor(loggingInterceptor);
        
        // Retrieve the server's conformance statement (CapabilityStatement)
        CapabilityStatement capabilities = client.capabilities().ofType(CapabilityStatement.class).execute();
        
        // Display information about the server
        String serverName = capabilities.getSoftware().getName();
        String serverVersion = capabilities.getSoftware().getVersion();
        
        System.out.println("Connected to FHIR server: " + serverName + " (version " + serverVersion + ")");
        System.out.println("Server Base URL: " + serverBaseUrl);
        System.out.println("FHIR Version: " + capabilities.getFhirVersion());
    }
}

This code connects to your HAPI FHIR server and prints a confirmation message along with server information.

Step 5 of 5: Test Your Connection

To test your connection to the FHIR server, you can run your application using Maven. This command will execute your Java application and verify if it can successfully connect to the FHIR server. Once you run the command, the application will establish a connection to the FHIR server using the base URL you provided. If the connection is successful, you should see a confirmation message indicating that your application is connected to the FHIR server at the specified URL. This message serves as a confirmation that your environment is properly set up and that your application can communicate with the FHIR server. Running the application and testing the connection is an important step in the setup process as it ensures that your application can interact with the FHIR server and perform the necessary operations on FHIR resources. It allows you to verify that your environment is correctly configured and that you can proceed with developing your healthcare application using the HAPI FHIR library and HAPI FHIR Server.

By testing your connection, you can ensure that your application is ready to retrieve, create, update, and delete FHIR resources as needed. This step is crucial in the development process as it validates the connectivity between your application and the FHIR server, enabling you to proceed with building robust and interoperable healthcare applications. Remember to regularly test your connection to the FHIR server throughout the development process to ensure that your application remains connected and can seamlessly interact with the FHIR resources. This will help you identify and resolve any connectivity issues early on, ensuring the smooth functioning of your healthcare application.

Run your application to ensure it can connect to the FHIR server:

mvn compile exec:java -Dexec.mainClass="com.saravanansubramanian.fhir.App"

You should see a message indicating a successful connection to your FHIR server, along with information about the server version and FHIR version supported.

Conclusion

You have successfully set up your environment for FHIR programming using Java and HAPI FHIR Server. In the next tutorial in this series, we will explore how to read FHIR resources from a server. See you then.