HL7 FHIR (Fast Healthcare Interoperability Resources) has become the dominant standard for healthcare data exchange. Regulatory mandates in the United States, national interoperability programmes across Europe, Australia, and beyond, and the growing ecosystem of patient-facing digital health applications have all converged on FHIR as the foundation for modern health IT integration. For healthcare developers and IT teams approaching FHIR for the first time — or moving from theory to implementation — this guide provides the practical grounding needed to build effective FHIR integrations.
What FHIR R4 Is
FHIR is a standard developed and maintained by HL7 International that defines how clinical and administrative health information should be structured and exchanged. The current stable release, FHIR R4 (Release 4), was published in 2019 and is the version in widest deployment globally. FHIR R5 has been published but adoption is still early.
FHIR uses modern web standards: RESTful HTTP APIs, JSON and XML for data serialisation, and OAuth 2.0 for authorisation. This aligns FHIR with the tools and skills of modern software development, reducing the learning curve compared to older healthcare standards like HL7 v2 and CDA (Clinical Document Architecture).
The core concept in FHIR is the resource: a discrete unit of healthcare information with a defined structure, a set of required and optional data elements, and a canonical URL that uniquely identifies its type. Resources are created, read, updated, and deleted via standard HTTP operations against a FHIR server endpoint.
The RESTful Resource Model
A FHIR server exposes resources via a base URL. A FHIR interaction follows predictable HTTP conventions:
GET /Patient/{id}— read a single patient recordGET /Patient?name=Smith&birthdate=1975-04-15— search for patientsPOST /Observation— create a new observationPUT /Patient/{id}— update an existing patient recordDELETE /MedicationRequest/{id}— delete a medication request
Key resource types and their clinical purpose:
Patient — demographic information: name, date of birth, gender, identifiers, contact details, GP or primary care provider. The Patient resource is the anchor for all other clinical resources.
Observation — clinical measurements and assessments: vital signs (blood pressure, heart rate, temperature), laboratory results (serum creatinine, haemoglobin), and clinical findings (body weight, pain score). Observations use LOINC codes to identify what is being measured.
Encounter — a clinical interaction between a patient and a healthcare provider. Encounters provide the context for observations, procedures, and diagnoses — linking clinical data to a specific visit, admission, or consultation.
DiagnosticReport — the report produced by a diagnostic service (laboratory, radiology, pathology). A DiagnosticReport may reference multiple Observation resources (individual test results) and may include narrative text alongside structured data.
MedicationRequest — a prescription or medication order. Contains the medication (identified via SNOMED CT or RxNorm), dose, route, frequency, prescriber, and authorising encounter.
Condition — a clinical condition, diagnosis, or problem. Used to represent the patient's problem list and to record diagnoses associated with encounters.
Procedure — a clinical action performed on or for a patient. Surgical procedures, diagnostic procedures, and administrative procedures are all represented using the Procedure resource.
Practitioner and Organization — represent the healthcare providers and organisations involved in care, supporting attribution of clinical data and care team management.
A FHIR server's capabilities are declared in its CapabilityStatement (available at GET /metadata), which lists the resource types supported, the interactions permitted for each type, and the search parameters available.
SMART on FHIR for Authorisation
SMART on FHIR (Substitutable Medical Applications, Reusable Technologies) is the authorisation and authentication framework built on top of OAuth 2.0 and OpenID Connect that enables third-party applications to securely access FHIR APIs with appropriate user consent and access controls.
SMART on FHIR defines two launch contexts:
- EHR Launch: The application is launched from within the EHR. The EHR passes context (patient ID, encounter ID, user identity) to the application as part of the launch sequence.
- Standalone Launch: The application launches independently and acquires context through the SMART authorisation flow.
SMART scopes define what data the application is requesting access to:
patient/Patient.read— read the current patient's Patient resourcepatient/Observation.read— read observations for the current patientuser/MedicationRequest.write— create medication requests on behalf of the authenticated user
SMART on FHIR is the mechanism by which patient-facing apps (Apple Health, consumer health apps), clinical decision support tools, and third-party analytics platforms are granted controlled access to EHR data. The US 21st Century Cures Act mandates that certified EHR systems support SMART on FHIR app launch and open API access to patient data.
Common FHIR Use Cases
Patient access apps: Consumer health applications that retrieve a patient's clinical record from their provider's EHR via FHIR APIs. Apple Health's Clinical Records feature, for example, uses FHIR R4 to pull medication lists, laboratory results, and immunisation records from participating health systems.
Provider directory: FHIR-based provider directories allow care coordination systems, referral networks, and scheduling applications to query for practitioner information, specialties, practice locations, and accepting-patient status.
Clinical data exchange: Care Everywhere (Epic), CommonWell, and national health information exchanges use FHIR to share patient records across organisational boundaries. A patient treated in an emergency department can have their prior records retrieved from their usual provider's EHR via a FHIR query.
Public health reporting: Immunisation registries, syndromic surveillance systems, and reportable condition notifications are increasingly built on FHIR resources rather than legacy HL7 v2 messaging.
Revenue cycle and payer integration: FHIR Bulk Data Access (the FHIR $export operation) enables payers and providers to exchange large datasets for prior authorisation, claims, and care gap analysis.
Implementation Guide Landscape
A base FHIR specification is deliberately broad. Implementation guides (IGs) constrain and extend the base standard for specific use cases and national contexts, defining which resources are required, which data elements are mandatory, and which code systems to use.
Key implementation guides:
US Core: Defines the minimum requirements for FHIR-based exchange in the US market, including mandatory support for specific resource types and the use of standard terminologies. US Core compliance is required for ONC certification of EHR systems.
International Patient Summary (IPS): Defines a FHIR-based representation of the minimum clinical data needed to support unplanned cross-border care. IPS is being adopted internationally as a standard for patient summary exchange.
SMART App Launch IG: Defines the SMART on FHIR authorisation framework in detail.
Implementation teams should identify which IGs are relevant to their use case and jurisdiction before beginning development. Building to a base FHIR specification without a relevant IG often produces integrations that are technically valid but not interoperable with the target systems.
Testing FHIR APIs
Postman is widely used for ad-hoc FHIR API testing. Pre-built FHIR Postman collections (available from Postman's public API Network) provide ready-made request libraries for common FHIR operations, reducing setup time.
HAPI FHIR is an open-source Java FHIR implementation that includes a public test server (hapi.fhir.org) and can be deployed locally as a development FHIR server. It is widely used for development and testing.
Touchstone (by AEGIS) is a dedicated FHIR testing platform that provides conformance testing against implementation guides, automated test scripts, and certification testing services. It is commonly used to verify implementation guide compliance before integration with partner systems.
Inferno is the ONC-designated testing tool for US Core and SMART App Launch conformance. EHR vendors seeking ONC certification use Inferno to demonstrate compliance.
Common Implementation Pitfalls
- Ignoring implementation guides: Building to the base FHIR spec without following the relevant IG produces non-conformant integrations that will not work with target systems.
- Underestimating terminology work: Mapping between local code systems and standard terminologies (SNOMED CT, LOINC, RxNorm) is significant effort. Terminology gaps are a common cause of data quality problems.
- Inadequate error handling: FHIR servers return OperationOutcome resources describing errors. Applications that do not parse and handle OperationOutcomes lose diagnostic information essential for debugging.
- Not testing against real systems: FHIR servers often have implementation-specific behaviours not captured in their CapabilityStatement. Testing against the actual target system before go-live is essential.
FHIR in the Cloud
Major cloud providers offer managed FHIR server services:
Azure Health Data Services (formerly Azure API for FHIR): Microsoft's managed FHIR R4 service, tightly integrated with Azure Active Directory for access control and Azure Monitor for logging and alerting.
AWS HealthLake: Amazon's FHIR-compatible data lake service, with built-in medical NLP for enriching unstructured clinical text and integrated analytics via Amazon Athena and QuickSight.
Google Cloud Healthcare API: Google's FHIR R4 service within its Healthcare API, integrated with BigQuery for analytics and with Vertex AI for machine learning on clinical data.
These managed services eliminate the operational burden of running FHIR server infrastructure and provide enterprise-grade availability, security, and scalability. For organisations building FHIR-based platforms, managed cloud FHIR services are typically preferable to self-hosted alternatives unless specific requirements (data residency, air-gapped environments) dictate otherwise.
FZ Consulting LLP provides FHIR integration advisory services and technical implementation support for healthcare organisations and digital health vendors. Contact us to discuss your FHIR integration requirements.