FHIR API Development Guide: Building Healthcare Interoperability in 2026

What is a FHIR API?

A FHIR API is a RESTful web service that exposes healthcare data as FHIR resources — structured, typed objects like Patient, Observation, Encounter, Medication, and DiagnosticReport. Each resource has a canonical URL, a JSON or XML representation, a set of CRUD operations (read, create, update, delete), and a standardized search interface.

The FHIR RESTful API follows standard HTTP conventions:

• GET [base]/Patient/123 — Read a specific patient resource by ID
• GET [base]/Patient?family=Smith&birthdate=1980-03-15 — Search for patients by name and birth date
• POST [base]/Patient — Create a new patient resource
• PUT [base]/Patient/123 — Update an existing patient resource
• DELETE [base]/Patient/123 — Delete a patient resource (rarely used in clinical contexts)

FHIR also supports Bundles — collections of multiple resources returned or submitted together — and Operations — named procedures like $everything (return all data for a patient) or $validate (validate a resource against a profile).

A FHIR server's CapabilityStatement (at [base]/metadata) declares exactly which resources, operations, search parameters, and profiles the server supports — making it machine-discoverable.

Core FHIR Resources for Healthcare Interoperability

FHIR R4 defines 140+ resource types. For most healthcare interoperability use cases, you will focus on a subset of high-priority resources aligned with the US Core Implementation Guide (currently US Core 6.1.0):

• Patient — Demographics, identifiers, contact information, and communication preferences. The anchor resource for all clinical data.
• Observation — Vital signs, lab results, social history, and clinical findings. Uses LOINC codes for standardized identification.
• Condition — Problems, diagnoses, and health concerns. Uses SNOMED CT or ICD-10 codes.
• MedicationRequest — Prescriptions and medication orders. References the Medication resource and uses RxNorm codes.
• Encounter — Clinical visits, admissions, and telehealth interactions. The context linking other clinical resources.
• Procedure — Surgical procedures, diagnostic studies, and clinical interventions. Uses CPT or SNOMED codes.
• AllergyIntolerance — Allergies and intolerances, including reaction severity and clinical status.
• Immunization — Vaccination history using CVX codes. Critical for immunization registry reporting.
• DiagnosticReport — Lab panels, radiology reports, and pathology results, grouping related Observations.
• DocumentReference — Clinical documents (C-CDA, PDF reports) stored or referenced through the FHIR server.
• Practitioner / Organization / Location — Provider directory resources required by CMS rules.
• Coverage / ExplanationOfBenefit — Insurance coverage and claims data required by the CMS Patient Access API.

Every resource you expose through a regulated FHIR endpoint must conform to the applicable US Core profile, which mandates specific must-support elements, required terminology bindings, and cardinality constraints.

SMART on FHIR Authorization

SMART on FHIR (Substitutable Medical Applications, Reusable Technologies) is the authorization framework layered on top of FHIR APIs. It combines OAuth 2.0 and OpenID Connect to enable secure, consent-based access to patient data by third-party applications.

SMART defines two primary launch contexts:

• EHR Launch: The app is launched from within the EHR (e.g., a clinician clicks a button in Epic). The EHR passes a launch token; the app exchanges it for an access token scoped to the current patient and context.
• Standalone Launch: The app launches independently and requests access from the FHIR server. The patient or clinician authenticates and consents before the app receives an access token.

SMART scopes control exactly what data the app can access:

• patient/Patient.read — Read the launched patient's demographic data
• patient/Observation.read — Read the patient's observations and lab results
• user/Patient.read — Read any patient the authenticated user can access
• system/Patient.read — Backend system access without a user context (used for bulk export)
• launch/patient — Request the patient context from the EHR
• openid fhirUser — Request identity information about the authenticated user

SMART App Launch Framework 2.0 (required for ONC g(10) certification) adds PKCE support, granular scopes, and token introspection. If you are building a certified health IT module, your authorization server must fully implement SMART App Launch 2.0.

Implementing SMART Authorization

Your FHIR server must expose a .well-known/smart-configuration endpoint that declares supported SMART capabilities, authorization endpoint, token endpoint, and supported scopes. Major identity providers (Keycloak, Azure AD B2C, Auth0) can be configured as SMART-compliant authorization servers with appropriate customization.

Building a FHIR Server: Implementation Options

You have several options for standing up a FHIR R4 server, ranging from open-source frameworks to fully managed cloud services:

Open-Source FHIR Servers

• HAPI FHIR (Java): The most widely deployed open-source FHIR server. Supports R4 and R5, US Core profiles, bulk export, and SMART on FHIR. Highly configurable but requires Java expertise and infrastructure management.
• Microsoft FHIR Server for Azure (C#/.NET): Open-source .NET implementation optimized for Azure deployment. The foundation of Azure Health Data Services.
• LinuxForHealth FHIR Server (IBM): Java-based server with strong support for FHIR profiles and terminology services.

Managed Cloud FHIR Services

• Azure Health Data Services: Fully managed FHIR R4/R5 service on Azure. Integrates with Azure Active Directory for SMART authorization, supports bulk export, and provides 99.9% SLA. Best choice for Azure-first organizations.
• AWS HealthLake: Managed FHIR R4 service on AWS with built-in NLP for unstructured clinical text and integrated analytics via Amazon Comprehend Medical.
• Google Cloud Healthcare API: Managed FHIR R4 service on GCP with strong BigQuery integration for analytics workloads.

Key Implementation Decisions

• Persistence layer: FHIR resources are typically stored in a relational database (PostgreSQL, SQL Server) or a document store (MongoDB, Azure Cosmos DB). HAPI FHIR uses JPA persistence; cloud services manage this transparently.
• Terminology services: FHIR servers need access to SNOMED CT, LOINC, RxNorm, and ICD-10 code systems for validation and translation. Consider integrating a terminology server (CSIRO Ontoserver, Snowstorm) for production deployments.
• Bulk Data Export: The FHIR Bulk Data Access (Flat FHIR) specification enables asynchronous export of large datasets using NDJSON. Required for population health, payer reporting, and public health use cases.

See our healthcare software development services for expert FHIR server implementation and managed hosting.

ONC and CMS Compliance Requirements

Federal regulations have made FHIR R4 compliance mandatory for a large segment of the healthcare industry. Understanding the applicable requirements is critical before starting development.

ONC 21st Century Cures Act Final Rule (g(10))

The ONC rule requires certified EHR vendors to provide a standardized API for patient and population services meeting these requirements:

• FHIR R4 with US Core profiles (currently US Core 3.1.1 minimum, 6.1.0 recommended)
• SMART App Launch Framework 2.0 authorization
• Support for all US Core resource types (Patient, Observation, Condition, MedicationRequest, etc.)
• No information blocking — the API must not restrict access to data that should be available
• Published API documentation and public developer access terms

CMS Interoperability and Patient Access Rule

The CMS rule applies to Medicare Advantage, Medicaid, CHIP, and qualified health plan issuers on Exchanges:

• Patient Access API: Expose adjudicated claims, encounters, clinical data, and formulary information via FHIR R4 to patient-authorized third-party apps.
• Provider Directory API: Expose provider network information (Practitioner, Organization, Location, HealthcareService) via FHIR R4 without authorization requirements.
• Payer-to-Payer API: Exchange member clinical and claims data between payers when a member switches plans. Uses FHIR Bulk Data Export.
• Prior Authorization API: Automate prior authorization processes using FHIR and the Da Vinci Prior Authorization Support (PAS) implementation guide.

For HIPAA compliance considerations in your FHIR implementation, see our HIPAA-Compliant HL7 Integration guide and our HIPAA compliance consulting services.

Testing & Validation

FHIR API testing requires a multi-layer approach covering conformance validation, security testing, and end-to-end workflow testing.

Conformance Validation

• HL7 FHIR Validator: The official HL7 validator checks resources against FHIR R4 base specifications and US Core profiles. Run it against every resource type you expose. Available as a Java CLI, Docker image, and web service.
• Inferno:The ONC's official test suite for g(10) certification. Inferno tests your FHIR server against US Core, SMART App Launch, and Bulk Data specifications. Your server must pass all required tests before ONC certification.
• Touchstone: A commercial FHIR testing platform supporting US Core, Da Vinci, and other implementation guide test scripts. Widely used for regression testing and pre-certification validation.

SMART Authorization Testing

• Test standalone and EHR launch flows with real OAuth 2.0 clients
• Verify scope enforcement — ensure apps cannot access data outside their granted scopes
• Test token expiration, refresh, and revocation flows
• Validate PKCE implementation for public clients

Performance and Load Testing

• FHIR search queries with broad parameters (e.g., Observation?patient=123&category=laboratory) can return thousands of resources. Test pagination, _count limits, and bundle navigation under load.
• Bulk export jobs processing millions of resources must complete within acceptable time windows. Test with realistic data volumes.

Integration Testing

End-to-end testing should validate complete workflows: a patient authorizing a third-party app, the app requesting an access token, querying patient data, and receiving correctly structured FHIR resources conforming to US Core profiles. Use synthetic patient data (Synthea-generated or MITRE FHIR test data sets) to avoid PHI exposure in test environments.

Ready to build a production-ready FHIR API? Contact our FHIR development team for architecture review and implementation support.