Skip to main content

The HAPI Echidna

High-Performance OMOP Terminology for HAPI FHIR​

HAPI FHIR is the gold standard for open source FHIR servers, but its internal terminology management can be resource-intensive, especially when dealing with massive datasets like SNOMED-CT or LOINC, and maintaining the latest versions of your terminologies can be a massive headache. Echidna (echidna.fhir.org) provides a cloud-native terminology server that bridges the gap between OMOP and FHIR, offering blazing-fast lookups and translations without the overhead of local database maintenance.

Switching to Echidna is super simple and free. Let’s see how to do this.

Prerequisites​

  • A running instance of HAPI FHIR JPA Starter (or a custom HAPI-based server).
  • Internet access for your server to reach https://echidna.fhir.org.
  • A basic understanding of the FHIR.

Option 1: Configuration via application.yaml​

If you are using the HAPI FHIR JPA Starter project, you can switch to Echidna by modifying your configuration file. This is the fastest "no-code" method.

  1. Open your application.yaml file.
  2. Add or modify the following properties:

YAML

hapi:
   fhir:
     # Enable remote terminology validation
     remote_terminology_service_enabled: true

     # Set the Echidna R5 endpoint
     remote_terminology_server_base_url: 'https://echidna.fhir.org/r5'

     # If you have an Echidna membership, you can specify it here:
     # remote_terminology_server_auth_token: 'your-echidna-token-here'

By setting these, HAPI will automatically delegate terminology operations it cannot resolve locally to Echidna.

Option 2: Java Configuration (Custom Implementation)​

For developers building a custom HAPI FHIR server using the IValidationSupport chain, you must manually inject the RemoteTerminologyServiceValidationSupport module.

Java

// 1. Initialize the FhirContext 
FhirContext ctx = FhirContext.forR5(); 

// 2. Create the Remote Terminology module pointing to Echidna
RemoteTerminologyServiceValidationSupport remoteTermSvc =
      new RemoteTerminologyServiceValidationSupport(ctx);
remoteTermSvc.setBaseUrl("https://echidna.fhir.org/r5"); 

// 3. Add it to your ValidationSupportChain 
ValidationSupportChain chain =
      new ValidationSupportChain(
           new DefaultProfileValidationSupport(ctx),
           new InMemoryTerminologyServerValidationSupport(ctx),
           remoteTermSvc // Delegated to Echidna
      );

With this option, when HAPI encounters a code validation request (e.g., checking if a SNOMED code is valid), it traverses the ValidationSupportChain. By placing the Echidna remote service in this chain, HAPI can leverage Echidna’s vast OMOP-mapped vocabulary library (10M+ concepts) as if they were stored locally.

Done!​

Simply restart the server for the changes to take effect. You can verify to see that everything works as promised.

Verifying the setup​

You can verify the integration by performing a $lookup operation through your HAPI server that requires Echidna's specialized OMOP-to-FHIR logic.

Example Request:

HTTP

GET http://your-hapi/fhir/CodeSystem/$lookup?\ 
    system=http://fhir-terminology.ohdsi.org&code=49495001

Or, if you are using CURL

Shell

$ curl http://your-hapi/fhir/CodeSystem/$lookup?\ 
       system=http://fhir-terminology.ohdsi.org&code=49495001

If everything is configured correctly, HAPI will forward this request to Echidna and return the concept details (Display: "Leukemia") retrieved from the remote server.