Skip to content

Broker

Intent

Provide a unified entry point for FHIR operations that routes requests to appropriate backend services based on capability, policy, and context.

Forces

  • Endpoint Capability Variation: FHIR servers implement different subsets of the specification, leading to compatibility issues.
  • Network Latency & Reliability: Healthcare networks often span institutions with varying connectivity quality.
  • Auditability & Trust: Healthcare systems must maintain comprehensive audit trails for regulatory compliance.
  • Legacy System Preservation: Healthcare organizations must modernize gradually while preserving existing clinical semantics and workflows.

Structure

The Broker pattern implements a mediation layer that routes FHIR requests to appropriate backend endpoints based on capability matching and policy enforcement.

FHIR Broker Class Diagram

Key Components

Broker

The main mediation component that receives client requests and routes them to appropriate endpoints

EndpointRegistry

Maintains a registry of available FHIR endpoints with their capabilities and metadata

CapabilityFacade

Wraps FHIR CapabilityStatement and SMART configuration to provide simplified capability queries

PolicyEngine

Applies authorization rules and consent policies to determine what data can be accessed

Endpoint

Represents a concrete FHIR server with its base URL, capabilities, and configuration

Behavior

Bulk Data Export Example

The following sequence shows how the Broker routes a bulk data export request to an appropriate endpoint:

FHIR Broker Bulk Data Export Sequence

Routing Algorithm

  1. Parse Request
  2. Query Registry
  3. Apply Policy
  4. Select Endpoint
  5. Route Request
  6. Process Response

Implementation Considerations

Capability Discovery

Configuration for discovering and caching endpoint capabilities. The broker queries each endpoint's CapabilityStatement to build a routing table.

Capability Discovery
# Example capability matching criteria
operation: $export
resourceTypes: [Group, Patient, Observation]
profiles: [us-core-patient, us-core-observation]
smartCapabilities: [system/*.read, bulk-export]

Policy Integration

The Broker integrates with consent and authorization systems: - SMART on FHIR: Validates tokens and enforces scopes - FHIR Consent: Applies patient consent decisions - Security Labels: Enforces data use restrictions

Error Handling

  • Capability Mismatch: Return 422 Unprocessable Entity with OperationOutcome
  • No Available Endpoints: Return 503 Service Unavailable
  • Authorization Failure: Return 401/403 with appropriate headers
  • Backend Errors: Transform and proxy error responses appropriately
  • Naming and Trading Service: Broker uses Naming/Trading for dynamic endpoint discovery and capability-based routing
  • Security Strategy: Security Strategy provides authentication context and token validation for Broker requests
  • Privacy Enforcement: Privacy Enforcement applies consent and data use restrictions through the Broker
  • Audit & Provenance Chain: Broker delegates audit logging and provenance tracking to the Audit & Provenance Chain
  • Asynchronous Invocation: Broker routes long-running operations to Async Invocation for non-blocking processing

Benefits

  • Unified Interface: Clients interact with a single, stable API
  • Dynamic Routing: Requests automatically flow to capable endpoints
  • Policy Enforcement: Consistent application of authorization and consent rules
  • Operational Visibility: Central point for monitoring and audit
  • Incremental Migration: Backend systems can be updated without client changes

Trade-offs

  • Single Point of Failure: Broker availability affects all clients
  • Performance Overhead: Additional network hop and processing
  • Complexity: More complex than direct client-server communication
  • State Management: Handling stateful operations (like async jobs) across endpoints

References

Real-world Usage

The Broker pattern is commonly used in health information exchanges (HIEs), cloud FHIR gateways, and multi-tenant FHIR platforms where multiple backend systems need to appear as a unified service.