How do you put FHIR APIs on top of a system that doesn't speak FHIR?
Most healthcare data does not live in a FHIR server. It lives in legacy databases, HL7 v2 feeds, and proprietary EHR schemas that predate FHIR by decades. A FHIR facade is the pattern that exposes standards-based FHIR APIs over those systems without ripping them out — a translation layer, not a migration. Done well, it gives partners and apps a clean FHIR surface while the systems of record stay put. Done poorly, it becomes a brittle mapping nobody can maintain. Here's how to build one that lasts.
What a FHIR facade is (and isn't)
A facade accepts FHIR requests, translates them into calls against the underlying system (SQL, an HL7 v2 interface, a vendor API), and maps the results back into valid FHIR resources. It is not a data migration and not a second source of truth — the legacy system remains authoritative. The facade is a stateless (or lightly cached) translation and conformance layer.
The core building blocks
- A FHIR API layer that implements the interactions you support (read, search, and sometimes create/update) and returns conformant resources.
- A mapping engine that translates between FHIR resources/elements and the legacy schema, including terminology mapping to LOINC/SNOMED/RxNorm.
- An adapter per source system — a SQL adapter, an HL7 v2 adapter (often via an interface engine like Mirth), or a vendor-API adapter.
- A conformance and validation layer so what you emit actually passes profile validation (e.g. US Core).
Read is easy; search is where facades get hard
Returning a single resource by id is straightforward. The difficulty is FHIR search: consumers expect parameters like Patient?identifier=, Observation?category=laboratory&date=ge2026-01-01, chained and _include queries, and paging. Each of those has to become an efficient query against a legacy store that was never designed for them. Naively translating FHIR search to SELECT * and filtering in memory is the classic facade performance failure.
- Map supported search parameters explicitly and reject unsupported ones with a clear OperationOutcome rather than returning wrong results.
- Push filtering, sorting, and paging down into the source query — never paginate in application memory over large sets.
- Decide up front which search parameters you support; you do not have to support every FHIR parameter, but you must be honest about which.
Identity and references
Legacy systems have their own identifiers; FHIR resources need stable logical ids and valid references between resources. A facade needs a deterministic id strategy (so the same legacy record always maps to the same FHIR id) and correct reference resolution (a MedicationRequest that points to the right Patient and Encounter). Getting identity wrong quietly corrupts every downstream integration.
Write-back: proceed with caution
Exposing create/update through a facade means translating FHIR writes into legacy mutations — with the legacy system's validation, side effects, and workflow rules. Many facades are read-only by design for exactly this reason. If you do support writes, treat the legacy system's business rules as the source of truth and surface its errors back as FHIR OperationOutcome.
Caching and performance
A facade sits in the hot path, so caching reference data (terminology, rarely-changing resources) and connection pooling to the source system matter. But cache invalidation against a live clinical system is genuinely hard — cache conservatively, and never cache in a way that could show a clinician stale medication or allergy data.
When a facade is the right call
A facade is ideal when the system of record must stay (regulatory, cost, risk) but you need modern interoperability now — to pass certification, onboard partners, or power apps and AI agents. It buys you a standards-based surface without a multi-year replatform, and it can later front a real migration without consumers noticing.
