Running and Interacting with Your Own HAPI FHIR Server in Local

Introduction

FHIR (Fast Healthcare Interoperability Resources) servers are very powerful for transferring and searching data. Many open-source FHIR servers are deployed online that can be accessed for free.

However, sometimes FHIR servers that are already deployed are not always adequate for a developer. To understand its underlying functionality and to do additional customization, we can set up our own local copy of the FHIR server using the HAPI server. With the HAPI FHIR server developers now can have complete control over how the data is stored, mapped, and customized.

Let’s begin with How to Configure and Run the Server

To deploy the local version of the HAPI FHIR Server, ensure that you have the following prerequisite.

• Head over to https://github.com/hapifhir/hapi-fhir-jpaserver-starter#configurationsamsung and clone the repository.

To configure and run the server, you have two paths: Using Docker and Using Java and Maven. Select the appropriate path and proceed further.

Option 1: Configure and Run the Server Using Docker

If you have chosen this path, ensure you have Docker installed in your local. If not, head over to Docker: Accelerated Container Application Development and install Docker.

Starting with the Deployment, Step 1: Configure Database

By default, the HAPI FHIR Server will use H2 as the database. If you wish to use other databases, like “Postgres,” continue with the configuration, or else skip to the next step. HAPI FHIR Server supports the PostgreSQL and Microsoft SQL Server database options, and we can choose any one of the options for running the server.

Follow the below steps for PostgreSQL Configuration

To Configure PostgreSQL as our Database, create a file with “hapi.application.yaml” inside the root folder of the GitHub repository which we cloned, and add the following database credentials.

spring:
  datasource:
    url: 'jdbc:postgresql://host.docker.internal:5432/<databasename>'
    username: <username>
    password: <password>
    driverClassName: org.postgresql.Driver
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.search.enabled: false

Make sure to update the fields <databasename>, <username>, and <password> as per your credentials.

Follow the below steps for Microsoft SQL Server Configuration.

To Configure Microsoft SQL Server as our Database, create a file with “hapi.application.yaml” inside the root folder of the GitHub repository which we cloned, and add the following database credentials.

spring:
  datasource:
    url: 'jdbc:sqlserver://<server>:<port>;databaseName=<databasename>'
    username: <username>
    password: <password>
    driverClassName: com.microsoft.sqlserver.jdbc.SQLServerDriver
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.search.enabled: false

Make Sure to update the fields <databasename>, <username>, and <password> as per your credentials.

Now that we have successfully configured our database, it is time to configure the server.

Step 2: Configure the Server

Update the docker-compose.yml file inside the root folder as follows:

version: '3.7'
 
services:
  fhir:
    container_name: fhir
    image: "hapiproject/hapi:latest"
    ports:
      - "8080:8080"
    configs:
      - source: hapi
        target: /app/config/application.yaml
 
configs:
  hapi:
     file: ./hapi.application.yaml

After updating the docker-compose.yml file, save it and proceed.

Step 3: Run the Server

Open a new terminal and run the server by executing the following command.

docker-compose up

It will take a while to start the server. Once it’s done, you will see the below output.

Fig 1: Server Status

The server will be accessible at http://localhost:8080.

Option 2: Configure and Run the Server Using Java and Maven

If you don’t want to use docker for running the server and want to run it locally make sure you have the following prerequisites installed.

1. Install Oracle Java (JDK) — Minimum JDK8 or newer — Download the Latest Java LTS Free.
2. Install Apache Maven build tool (newest version) — Maven — Welcome to Apache Maven.

Once you have installed them proceed further.

Step 1: Configure Database

As mentioned in the previous step — “Configure and Run the Server Using Docker” by default, the HAPI FHIR Server will use H2 as the database. If you wish to use other databases, like “Postgres,” continue with the configuration, or else skip to the next step. HAPI FHIR Server supports the PostgreSQL & Microsoft SQL Server database options, and we can choose any one of the options for running your server.

Using PostgreSQL Configuration:

To use PostgreSQL, instead of the default H2, update the ‘application.yaml’ file inside src/main/resources/application.yaml and update the values below the spring as follows:

spring:
  datasource:
    url: 'jdbc:postgresql://localhost:5432/<databasename>'
    username: <username>
    password: <password>
    driverClassName: org.postgresql.Driver
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.search.enabled: false

      # Then comment all hibernate.search.backend.*

Make sure to update the fields <databasename>, <username>, and <password> as per your credentials.

Using Microsoft SQL Server Configuration:

To use Microsoft SQL Server, instead of the default H2, update the ‘application.yaml’ file inside src/main/resources/application.yaml and update the values below the spring as follows.

spring:
  datasource:
    url: 'jdbc:sqlserver://<server>:<port>;databaseName=<databasename>'
    username: admin
    password: admin
    driverClassName: com.microsoft.sqlserver.jdbc.SQLServerDriver

If you’re using the JDK/ Maven configuration make sure you are not setting the Hibernate dialect explicitly. In other words, remove any lines similar to those below from the src/main/resources/application.yaml.

hibernate.dialect: {some none Microsoft SQL dialect}

Make sure to update the fields <databasename>, <username>, and <password> as per your credentials.

Step 2: Run the Server

To run the server, you have two ways.

1. Using Jetty

To run the server using Jetty, open a new terminal and execute the following command:

mvn -Pjetty jetty:run

2. Using Spring Boot

To run the server using Spring Boot, open a new terminal and execute the following command:

mvn clean package spring-boot:repackage -Pboot && java -jar target/ROOT.war

If you have executed any of the above commands, you will see the below output.

Fig 2: Server Status

The Server will be accessible at http://localhost:8080.

Testing the Server

Our server is now up and running. To ensure this head over to http://localhost:8080/fhir. If everything works fine, you will see the HAPI server homepage shown below.

Fig 3: HAPI FHIR UI

To see your server capability use http://localhost:8080/fhir/metadata.

Fig 4: Server Capability

Interacting with the Server

Now, we have our own local copy of the FHIR server. Since the server is utilizing our local database and there won’t be any data inside it, let’s add some data to it.

I will be using Download Postman | Get Started for Free for adding the data but feel free to use any tool such as Desktop API Design Editor and API Client.

1. Use the following dummy JSON to create our first Patient Resource.

{
    "resourceType": "Patient",
    "name": [
        {
            "use": "official",
            "given": ["Adam"],
            "family": "John"
        }
    ],

    "gender": "male",
    "birthDate": "1989-01-01",
    "telecom": [
        {
            "value": "9511199632",
            "use": "mobile",
            "system": "phone"
        },{
            "value": "adam@xyz.com",
            "system": "email"

        }
    ],

    "address": [
        {
            "line": [
                "32/1110 C1 Heaven House"
            ],
            "city": "XYZ",
            "state": "ABC",
            "postalCode": "960000"
        }
    ]
}

2. Send a post request to http://localhost:8080/fhir/Patient using the above JSON value and “Content-Type” as “application/json”. Make sure all the fields satisfy the datatypes that are allocated for them by the server.

For example, instead of a string value for gender if you give an integer value the server will throw an error.

Fig 5: POST Patient API

If you have followed the proper resource structure, the server will add the resource to the database and generate an ID for your resource.

Fig 6: POST API Response

In the above image, you can see the server generated an id for us. Using this ID, we can retrieve the Patient details by making a GET request to the following API endpoint http://localhost:8080/fhir/patient/{id}.

Perform CRUD operation using resources that are available in HL7 — FHIR by changing the API Endpoint as follows http://localhost:8080/fhir/{RESOURCE_NAME} and the API Method.

Conclusion

Now, we have our own local copy of the HAPI FHIR Server up and running. The local setup will provide all the functionalities of the FHIR server and HAPI server. Feel free to play with it to explore the power of the HAPI FHIR server.