FHIR Facade

The northbound API in a facade architecture. A software application that exposes a standards-compliant RESTful API for creating, reading, updating, and searching FHIR resources. In a facade pattern, the FHIR server does not persist data natively but translates incoming requests into the backend's native query language, such as SQL or a proprietary EHR API. The facade server handles authentication, authorization, logging, and response formatting, presenting a clean FHIR interface to consumers while masking the complexity of the legacy system behind it.

A domain-specific language designed by HL7 to author the transformation rules that convert legacy healthcare data formats into FHIR resources. It is the engine inside a FHIR Facade. The language defines how source fields from a relational database, HL7 v2 message, or CDA document map to target FHIR elements. Key concepts include:

• Nested expressions for handling complex hierarchical data
• Conditional logic to handle optionality and data-driven branching
• Lookup tables for translating local codes to standard terminologies like SNOMED CT The compiled map executes at query time, enabling real-time, on-the-fly transformation without ETL.

A container resource that groups multiple FHIR resources together as a single unit for transmission. In a facade context, a single API call for a patient's full record may require the facade to query multiple backend tables (demographics, allergies, medications) and assemble the results into a searchset bundle. The facade must handle pagination links and total counts, translating the backend's cursor-based or offset pagination into FHIR's Bundle.link format. Transaction bundles add complexity, requiring the facade to orchestrate atomic commits across disparate backend systems.

A definition that specifies how a client can query a FHIR server for resources based on the value of a specific element. The facade must parse incoming search parameters like Patient?name=Smith and translate them into the backend's query syntax. This involves:

• Chained parameters: Resolving Patient?organization.name=General requires joining across backend tables
• Modifiers: Handling :exact, :contains, and :missing semantics in the target query language
• Composite parameters: Combining multiple fields into a single backend index scan
• _include and _revinclude: Fetching referenced resources in a single response to avoid N+1 query problems

A FHIR resource returned by a server to provide detailed information about the success or failure of an operation. In a facade implementation, the mapping layer must catch and translate backend errors into meaningful OperationOutcomes. A foreign key violation in the database becomes an invalid code with a diagnostic message. A timeout from the legacy system becomes a transient issue with a retry hint. Proper error mapping is critical for debugging and ensures the facade behaves as a well-behaved FHIR citizen, not a leaky abstraction.

A software tool that checks FHIR resources and profiles against the specification's rules, constraints, and terminology bindings. In a facade architecture, the validator serves as a quality gate on the northbound interface. Before returning a generated resource to the client, the facade can run it through a validator to ensure the mapping logic produced a conformant output. Common validation checks include:

• Cardinality: Required elements are present
• Terminology binding: Coded values exist in the specified ValueSet
• Invariants: Complex co-constraints between elements are satisfied This catches mapping errors early and prevents non-conformant data from propagating downstream.