Skip to main content

​
Overview

HAPI FHIR can use OMOPHub as an external terminology service for code validation, concept lookup, and cross-vocabulary translation. This replaces the need to download and host ATHENA vocabulary files locally. One configuration change. No database setup, no vocabulary downloads, no maintenance.

​
Quick Setup

​
YAML Configuration

Add to your HAPI FHIR application.yaml: 
hapi:
  fhir:
    validation:
      remote_terminology_service_enabled: true
      remote_terminology_service_urls:
        - url: "https://fhir.omophub.com/fhir/r4"
          auth:
            type: bearer
            token: "oh_your_api_key_here"

​
Java Configuration

For custom HAPI FHIR server builds: 
@Configuration
public class TerminologyConfig {

    @Bean
    public IValidationSupport remoteTermService() {
        RemoteTerminologyServiceValidationSupport remote =
            new RemoteTerminologyServiceValidationSupport(
                FhirContext.forR4()
            );
        remote.setBaseUrl("https://fhir.omophub.com/fhir/r4");

        // Add API key authentication
        remote.addClientInterceptor(new BearerTokenAuthInterceptor("oh_your_api_key_here"));

        return remote;
    }
}

​
Spring Boot Properties

hapi.fhir.remote_terminology_service_enabled=true
hapi.fhir.remote_terminology_server_base_url=https://fhir.omophub.com/fhir/r4
Authentication must be configured separately when using properties files. Use the Java configuration approach above to set the Bearer token via BearerTokenAuthInterceptor, or configure it through your YAML config (remote_terminology_service_urls[].auth.token). The properties-file remote_terminology_server_base_url is the single-server equivalent of the YAML remote_terminology_service_urls array.

​
Verify It Works

After configuration, test with a simple $lookup: 
# Through your HAPI server (it will proxy to OMOPHub)
curl "http://localhost:8080/fhir/CodeSystem/\$lookup?\
system=http://snomed.info/sct&code=44054006"

# Or directly against OMOPHub
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?\
system=http://snomed.info/sct&code=44054006" \
  -H "Authorization: Bearer oh_your_api_key"
Both should return the same FHIR Parameters response with concept details.

​
What OMOPHub Adds vs Local ATHENA

CapabilityOMOPHubLocal ATHENA + HAPI
Setup time1 minute (config change)Hours (download, DB, HAPI config)
Vocabulary updatesAutomaticManual quarterly download
InfrastructureNone (cloud API)PostgreSQL + HAPI server
Semantic searchYesNot available
FHIR R4/R5/R6All threeR4 only (typical)
$translate with target-tableYesNo
Phoebe recommendationsYes (opt-in)Not available

​
Supported Operations

When configured as a remote terminology service, HAPI FHIR will use OMOPHub for:
  • Code validation ($validate-code) - validating codes during resource validation
  • Code lookup ($lookup) - resolving concept details
  • Code translation ($translate) - mapping between vocabularies

​
Rate Limits

FHIR operations share the same quota as REST API calls. For high-volume HAPI servers, consider a Pro or Enterprise plan for higher rate limits.

​
Troubleshooting

“Connection refused” or timeout:
  • Verify API key: curl -H "Authorization: Bearer oh_xxx" https://fhir.omophub.com/fhir/r4/metadata
  • Check network access to fhir.omophub.com:443
“Unknown code system”:
  • OMOPHub supports the major vocabularies (SNOMED, ICD-10, LOINC, RxNorm, etc.)
  • CPT4 is excluded due to AMA licensing
  • See the TerminologyCapabilities for the full list
R4 vs R5 mismatch:
  • Use /r4 for HAPI FHIR R4 servers (default)
  • Use /r5 for HAPI FHIR R5 servers
  • The base URL in your config must match your HAPI FHIR version

​
Get Your API Key

Sign up at omophub.com and create an API key in your dashboard. Free tier includes 3,000 calls/month.