FHIR R4 is the backbone of modern healthcare interoperability, and for US developers it is effectively the version that matters — it is the release US regulation is built around, from ONC’s certification API criterion to the CMS interoperability rules. Implementing it well, though, takes more than reading and writing a few resources. You have to understand the resource model, the RESTful API and its search semantics, the profiles that constrain base resources for US use, terminology handling, authorization via SMART on FHIR, and how to validate that what you built actually conforms. This guide is a practical orientation to all of it — enough to plan a real FHIR R4 implementation and avoid the common traps.
A quick scope note: this is a technical guide, not legal advice, and when your implementation handles real patient data, that data is PHI and must be protected accordingly (encryption, access control, and a BAA where applicable). With that said, let’s get into the engineering.
Why R4 Specifically
FHIR has several releases — STU3, R4, and the newer R5 — but for US healthcare interoperability, R4 is the center of gravity. It is the version referenced by ONC’s standardized API certification criterion and the CMS interoperability and prior authorization rules, which means if you are building to integrate with certified EHRs or to meet US regulatory requirements, you are building to R4 (and the US Core profiles layered on it). R5 exists and will matter more over time, but R4 is where the regulatory ecosystem, the EHR support, and the tooling are concentrated today. Building on R4 is the pragmatic default for US work — see our CMS interoperability compliance work for the regulatory side, and our HL7 vs FHIR comparison for how FHIR relates to the older HL7 v2 world.
FHIR Fundamentals: Resources and the RESTful API
FHIR’s core idea is resources — modular, self-contained units of healthcare data like Patient, Observation, Condition, MedicationRequest, Encounter, and many more (R4 defines around 145 resource types). You compose your data out of these resources and the references between them (an Observation references a Patient, a MedicationRequest references both, and so on), rather than dealing in monolithic documents. Resources use defined data types and can carry extensions where the base model does not cover a need.
The API is RESTful and predictable: standard HTTP interactions for create, read, update, and delete on resources, plus search, history, and transaction/batch operations for doing several things at once. This is one of FHIR’s biggest advantages over older standards — developers who know REST and JSON are most of the way to being productive, because FHIR behaves like the web APIs they already understand. Getting the resource modeling and the reference graph right early is the foundation everything else builds on.
Search: Where the Real Work Is
Reading a resource by ID is easy; the power and the complexity are in search. FHIR defines search parameters per resource, with modifiers, chaining (searching across references), and inclusion of related resources via _include and _revinclude so you can pull a resource and its connected data in one query. Implementing search well — supporting the parameters consumers actually need, handling pagination, and returning correct results efficiently — is often the largest part of a FHIR API build. It is also where naive implementations struggle at scale, so search deserves deliberate design rather than being treated as a thin layer over a database.
Profiles and US Core: The Part US Developers Cannot Skip
Base FHIR resources are intentionally broad, and real interoperability requires profiles that constrain them — specifying which elements are required, which value sets apply, and how resources are used for a given purpose, all expressed through StructureDefinitions. For US healthcare, the essential one is US Core, the implementation guide that defines the baseline expectations for US interoperability and is built on USCDI (the United States Core Data for Interoperability). If you are building for US interop or certification, conforming to the appropriate US Core version is not optional — it is what makes your data exchangeable with certified systems. A frequent and costly mistake is implementing base FHIR while ignoring US Core, then discovering the data does not actually interoperate. Build to US Core from the start.
Terminology: Codes, Value Sets, and Services
Healthcare data is heavily coded, and FHIR handles this through code systems and value sets (LOINC for labs and observations, SNOMED CT for clinical concepts, RxNorm for medications, ICD for diagnoses, and others). A real implementation needs to handle terminology properly — using the right codes, binding elements to the correct value sets, and often using terminology services (operations like $expand to expand a value set and $validate-code to check a code) rather than hard-coding. Weak terminology handling is a common source of interoperability failures, because data that uses the wrong codes or unvalidated codes will not be understood correctly by the systems you exchange with.
SMART on FHIR: Authorization You Can’t Ignore
A FHIR API exposing PHI needs authorization, and the standard for that is SMART on FHIR, which layers OAuth2 on FHIR. SMART App Launch defines how apps authenticate and obtain scoped access — including the EHR launch flow (an app launched from within an EHR session) and the standalone launch flow — using scopes to control what data an app may access. If you are building an app that integrates with EHRs, or an API that third-party apps will connect to, SMART is how access is granted and constrained securely. Underestimating authorization is a classic mistake; it is foundational, not an afterthought, and it is central to EHR integration — see our Epic integration work for how SMART plays out in practice.
Bulk Data and Conformance
Two more pieces round out a serious implementation. FHIR Bulk Data (sometimes called Flat FHIR) defines the $export operation for moving population-level data efficiently — essential for analytics, population health, and the bulk-access expectations in US regulation. And conformance is declared through the CapabilityStatement (available at the server’s metadata endpoint), which tells clients exactly what your server supports — which resources, interactions, search parameters, and profiles. A correct CapabilityStatement is part of being a well-behaved FHIR server, and consumers rely on it to understand your API.
Validation: Prove It Conforms
Building to the spec is not the same as conforming to it, so validation matters. You validate resources against the base spec and against the profiles (US Core and any of your own) to confirm they are well-formed and conformant, using FHIR validation tooling. For ONC certification specifically, ONC’s Inferno test suite validates conformance to the certification API criteria. Validating throughout development — not just at the end — catches conformance gaps early, when they are cheap to fix, rather than during integration testing with a partner who rejects your non-conformant data.
Choosing Your FHIR Infrastructure
You rarely build a FHIR server from scratch, and you usually should not. The main paths are an open-source FHIR server like HAPI FHIR (Java, mature, highly extensible) that you host and operate; a managed cloud FHIR service such as Azure Health Data Services, AWS HealthLake, or Google Cloud Healthcare API; or an enterprise platform like Smile CDR built on HAPI with added modules and support. The right choice depends on your control, hosting, compliance, and operational preferences — managed services reduce operational burden, while self-hosted options maximize control. See our Azure API for FHIR, AWS HealthLake, and Smile CDR practices for the options. Reinventing a FHIR server when a mature one fits your needs is a classic waste of effort.
Common Implementation Pitfalls
The recurring mistakes: ignoring US Core profiles and implementing only base FHIR, so the data does not truly interoperate; weak terminology handling that produces data others cannot understand; underestimating SMART/authorization and treating it as an afterthought; version confusion between R4, R5, STU3, and across US Core versions; skipping validation until integration, when conformance gaps become expensive; and building a FHIR server from scratch when a mature open-source or managed option would have served. Designing against these from the start is most of what makes a FHIR implementation succeed.
Getting Started Practically
Pin Your Versions
Choose FHIR R4 and the appropriate US Core version up front, and hold to them, so the whole team builds to the same target.
Choose Your FHIR Infrastructure
Decide between a self-hosted server (HAPI), a managed cloud service, or an enterprise platform based on control, compliance, and operations.
Model Your Data to Resources and Profiles
Map your data onto FHIR resources and conform it to US Core profiles, getting the resource and reference model right early.
Implement the API and Search
Build the RESTful interactions and, critically, robust search with the parameters consumers need.
Handle Terminology
Use correct code systems and value sets, with terminology services for expansion and validation.
Implement SMART Authorization
Add SMART on FHIR authorization with appropriate scopes and launch flows.
Validate Continuously
Validate against the spec and profiles throughout, using FHIR validators and, for certification, Inferno.
How Taction Helps
We implement FHIR R4 end to end — modeling data to resources and US Core profiles, building RESTful APIs with robust search, handling terminology properly, implementing SMART on FHIR authorization, adding Bulk Data export, and validating conformance throughout. We help you choose and stand up the right infrastructure, whether self-hosted HAPI, a managed cloud FHIR service, or an enterprise platform, and we handle PHI under a signed BAA with ISO 27001-certified security. Our FHIR API development practice, within our broader healthcare software work, covers the full implementation.
Related reading: SMART on FHIR: Building Your First App · HL7 v2 to FHIR Migration: A Practical Guide
Frequently Asked Questions
Should I build on FHIR R4 or R5?
For US healthcare interoperability, R4 — it is the version US regulation, certified EHR support, and tooling are built around today. R5 exists and will grow in relevance over time, but R4 (with US Core profiles) is the pragmatic default for US work. Pin your version early to avoid confusion.
What is US Core and do I need it?
US Core is the US baseline FHIR implementation guide, built on USCDI, that defines required elements and expectations for US interoperability. If you are building for US interop or certification, conforming to the appropriate US Core version is essential — implementing only base FHIR without US Core is a common reason data fails to truly interoperate.
How hard is FHIR search to implement?
It is usually the largest part of a FHIR API build. Reading by ID is simple, but supporting the search parameters, modifiers, chaining, and inclusions consumers need, with correct pagination and good performance, takes deliberate design. Naive search implementations tend to struggle at scale.
Do I need SMART on FHIR?
If your FHIR API exposes PHI or integrates with EHRs, yes — SMART on FHIR (OAuth2-based) is the standard for authenticating apps and scoping their access, including EHR and standalone launch flows. Authorization is foundational, not an afterthought, and EHR integrations depend on it.
Should we build our own FHIR server?
Usually not. Mature open-source servers like HAPI FHIR, managed cloud FHIR services, and enterprise platforms like Smile CDR cover most needs. Building from scratch is rarely justified; choose based on your control, compliance, and operational preferences instead.
How do we know our implementation conforms?
Validate continuously against the base spec and the relevant profiles (US Core and your own) using FHIR validation tooling, and for ONC certification use ONC’s Inferno test suite. Validating throughout development catches conformance gaps early, rather than during integration when they are expensive to fix.
Implementing FHIR R4 and want it done right? Schedule a free consultation →
This article is a technical guide, not legal advice. Reviewed by Taction Software’s healthcare engineering team. ISO 27001-certified information security management. PHI handled in a FHIR implementation is protected under a signed BAA.
