What Is a FHIR API? HL7 FHIR R4 Architecture, RESTful CRUD, SMART on FHIR, and Bulk Data ($export)

A FHIR API (Fast Healthcare Interoperability Resources Application Programming Interface) is a standards-based, RESTful web interface defined by Health Level Seven International (HL7) that enables electronic health records (EHRs), patient mobile apps, payer systems, and clinical research platforms to exchange discrete healthcare data over HTTPS using modern JSON, XML, and OAuth 2.0 web protocols. Mandated across U.S. certified EHR technology under the ONC 21st Century Cures Act Final Rule (45 CFR § 170.315(g)(10)), HL7 FHIR Release 4 (R4) replaces brittle, point-to-point HL7 v2 pipe-delimited messages and monolithic C-CDA XML documents with modular, addressable clinical resources.

What Is a FHIR API? Modular Resource and RESTful CRUD Architecture

Unlike legacy HL7 v2 interfaces—which require custom per-hospital segment parsing over persistent TCP/MLLP sockets—or Consolidated Clinical Document Architecture (C-CDA) files that transmit an entire multi-page clinical summary even when an application only needs a single potassium value, a FHIR API models healthcare data as ~145 composable Resources. Each resource has a canonical URL, a defined JSON/XML schema, human-readable XHTML narrative text, and standard terminology bindings (such as SNOMED CT, LOINC, RxNorm, and ICD-10-CM):

• Foundational & Administrative Resources: Patient, Practitioner, Organization, Location, Encounter, and Endpoint.
• Clinical & Diagnostic Resources: Condition (problem list diagnoses), Observation (laboratory results, vital signs, social determinants, and smoking status), Procedure, AllergyIntolerance, DiagnosticReport, and Immunization.
• Medication & Care Planning Resources: MedicationRequest, MedicationStatement, MedicationAdministration, CarePlan, CareTeam, and Goal.
• Financial & Clinical Research Resources: Coverage, ExplanationOfBenefit (EOB), Claim, ResearchStudy, and ResearchSubject.

Every FHIR API exposes standard HTTP RESTful CRUD and Search interactions over TLS using the MIME type application/fhir+json (or application/fhir+xml):

FHIR Interaction	HTTP Method & Endpoint Pattern	Clinical Informatics Operation
Read / vRead	GET [base]/Patient/12345 GET [base]/Patient/12345/_history/2	Retrieves the current state (or a specific historical version) of a single resource by logical ID
Search	GET [base]/Observation?patient=12345&category=laboratory&code=http://loinc.org|4548-4	Queries matching resources (e.g., all HbA1c lab observations for a patient) returned inside a FHIR Bundle (type: "searchset")
Create	POST [base]/DocumentReference	Writes a new resource (such as an ambient AI clinical note or external PDF report) into the EHR
Update / Patch	PUT [base]/Condition/9876 PATCH [base]/Condition/9876	Replaces or partially updates an existing resource using optimistic concurrency control (If-Match: W/"version")
Extended Operations	GET [base]/Patient/12345/$everything GET [base]/Group/trial-cohort/$export	Executes server-side operations such as full patient record assembly or asynchronous Bulk Data NDJSON export

ONC 45 CFR § 170.315(g)(10), US Core Profiles, and SMART on FHIR Security

Because base HL7 FHIR R4 is an international specification designed to accommodate global healthcare systems, many base resource fields are optional. To guarantee plug-and-play interoperability across U.S. enterprise EHRs—such as Epic Systems, Oracle Health (Cerner), and MEDITECH Expanse—the Office of the National Coordinator for Health Information Technology (ONC) Cures Act Final Rule (45 CFR § 170.315(g)(10)) enforces three binding specifications:

1. HL7 FHIR US Core Implementation Guide: Constrains base FHIR R4 resources to map directly to the United States Core Data for Interoperability (USCDI), defining Must Support elements, mandatory search parameters, and required value set bindings (SNOMED CT, LOINC, RxNorm, CVX).
2. SMART on FHIR App Launch Framework (OAuth 2.0 & OpenID Connect): Provides the authorization and single-sign-on layer for FHIR APIs. SMART on FHIR supports two launch flows: EHR Launch (where a clinician opens a third-party app directly inside an active EHR chart session, automatically receiving `launch/patient` context) and Standalone Launch (where a patient or researcher launches a mobile/web app outside the EHR and authenticates via the hospital’s patient portal or identity provider). Granular SMART v1/v2 scopes (such as patient/Observation.rs or user/Condition.rs) enforce least-privilege access.
3. CMS Interoperability and Prior Authorization APIs (CMS-9115-F & CMS-0057-F) and TEFCA: Beyond hospital EHRs, CMS mandates that Medicare Advantage, Medicaid, CHIP, and Qualified Health Plan payers expose FHIR R4 Patient Access APIs, Provider Access APIs, Payer-to-Payer APIs, and Prior Authorization APIs (Da Vinci PAS/CRD/DTR), while TEFCA Qualified Health Information Networks (QHINs) adopt Facilitated FHIR for nationwide network exchange.

FHIR Bulk Data Access ($export) and Clinical Research Integration

While single-patient RESTful `GET` calls are ideal for bedside apps, querying 50,000 patients one by one for a clinical registry or real-world evidence study would overwhelm transactional EHR servers. To solve population-scale extraction, ONC-certified FHIR APIs implement the HL7 FHIR Bulk Data Access (Flat FHIR) specification:

• Asynchronous Kick-Off and NDJSON Retrieval: A registered backend service authenticates via SMART Backend Services (OAuth 2.0 client_credentials with asymmetric RS384/ES384 JWT assertions) and issues an asynchronous kick-off request (GET [base]/Group/[id]/$export) with header Prefer: respond-async. The FHIR server returns HTTP 202 Accepted with a Content-Location polling URL, compiles the cohort records in the background into Newline Delimited JSON (.ndjson) files grouped by resource type, and provides a manifest of download URLs for ingestion into CDISC ODM/SDTM or OMOP Common Data Model pipelines.

Frequently Asked Questions

What is a FHIR API?

A FHIR API (Fast Healthcare Interoperability Resources API) is a standardized, RESTful web interface defined by HL7 that represents healthcare data as modular JSON or XML resources (such as Patient, Observation, Condition, and MedicationRequest) accessed via standard HTTPS CRUD operations and secured with OAuth 2.0 (SMART on FHIR).

What is the difference between a single-patient FHIR API and Bulk FHIR ($export)?

A single-patient FHIR API uses synchronous HTTP GET/POST calls authorized via SMART App Launch to retrieve or update records for one patient at a time in real time. The FHIR Bulk Data Access ($export) API uses asynchronous backend service authentication to export multi-patient cohorts as Newline Delimited JSON (.ndjson) files for population health, quality measurement, and clinical research.