Running a Local HAPI FHIR Server For Testing HL7 FHIR Requests

When implementing FHIR, a FHIR server is essential for validating and process incoming FHIR requests from clients. Also, it will be the place where you store your customized profiles, valuesets, and codesystems that is necessary for managing terminology.

HAPI FHIR is the most popular FHIR server available at the moment and has been available for several years. It’s fully open-source software which means anyone can download and host it to experiment with it to get their hands dirty with FHIR.

In this post, I’m going to show how you can install the hapi fhir server on your computer for development and testing fhir requests.

Download HAPI with Docker

The easiest way to download HAPI is with Docker. The repository is available on Docker Hub at the following address : https://hub.docker.com/r/hapiproject/hapi

Pull the latest hapi fhir server to your computer. After the pull is complete, you can run the hapi fhir server with the following command.

docker pull hapiproject/hapi:latest

Run the following command to start the HAPI FHIR server on port 8080

docker run -p 8080:8080 hapiproject/hapi:latest

Navigating to http://127.0.0.1:8080 you will be able to see the the standard HAPI FHIR screen.

Making a request to HAPI FHIR server

Now you can make requests to your local setup HAPI FHIR server to perform different actions that you would do on a real FHIR server. Such as creating, updating, deleting, searching for different resources, uploading profiles, valuesets etc.

In order to make a simple request, open the Postman client or Hoppscotch.io and make the following post request to the Patient endpoint to create a new patient resource.

{
  "resourceType": "Patient",
  "extension": [ {
    "url": "http://hl7.org/fhir/StructureDefinition/us-core-race",
    "valueCodeableConcept": {
      "coding": [ {
        "system": "http://hl7.org/fhir/v3/Race"
      } ]
    }
  }, {
    "url": "http://hl7.org/fhir/StructureDefinition/us-core-ethnicity",
    "valueCodeableConcept": {
      "coding": [ {
        "system": "http://hl7.org/fhir/v3/Ethnicity"
      } ]
    }
  } ],
  "identifier": [ {
    "id": "5fdfe7f0-5fd1-4675-a800-417042d3ebdd",
    "use": "usual",
    "type": {
      "coding": [ {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code": "MR"
      } ]
    },
    "system": "urn:oid:1.2.36.146.595.217.0.1",
    "value": "129862",
    "assigner": {
      "display": "MCH"
    }
  }, {
    "system": "http://new-republic.gov/galactic-citizen-identifier",
    "value": "213445556"
  }, {
    "system": "http://caringly.tech/hospital-patient-identifier",
    "value": "MCH@HNAM@129862"
  } ],
  "active": true,
  "name": [ {
    "use": "official",
    "family": "MEDSURGTELE",
    "given": [ "EIGHT" ]
  } ],
  "telecom": [ {
    "system": "phone",
    "value": "(123)344-2556",
    "use": "home",
    "rank": 1
  }, {
    "system": "phone",
    "use": "work",
    "rank": 2
  } ],
  "gender": "female",
  "birthDate": "1990-01-08",
  "deceasedBoolean": false,
  "address": [ {
    "use": "home"
  } ],
  "generalPractitioner": [ {
    "identifier": {
      "use": "official",
      "system": "http://caringly.tech/hospital-provider-identifier"
    }
  } ],
  "managingOrganization": {
    "reference": "Organization/582205"
  }
}

If successful, you will receive a response with status code of 200 and a resource with id of 1 (this is the first patient resource that we just created on the server) and of resource type of Patient.

You can make more requests and get to know your way around HAPI FHIR.

HAPI FHIR server for production

The method described above is only good for a development environment and not for a production environment. You will have to serve HAPI FHIR through something like Apache Tomcat to incorporate HAPI FHIR in a production environment.

HAPI FHIR server does not act as a FHIR authorization server, so there is no way to authorize incoming requests based on the requesting clients. For that, you will have to incorporate an authorization server such as FHIR Auth.

I’ll write a post on how to deploy HAPI FHIR on Apache Tomcat in a production environment in a later post. Feel free to shoot any questions via Twitter or in the comments.