FHIR: Resources and the REST API

HL7 v2, from the previous lesson, is a pipe-delimited text format designed before the web. FHIR (Fast Healthcare Interoperability Resources), first published by HL7 in 2014 and led by Grahame Grieve, was a deliberate reset: keep the practical, implementer-first spirit of v2, but build on ordinary web technology.

That means three things a web developer already knows: data as resources, exchanged over a REST API, in JSON (or XML). No custom delimiters, no positional parsing. If you can call a REST endpoint and read JSON, you can read FHIR. This is why FHIR is the standard now mandated for new work, especially patient-facing apps and payer-to-provider exchange. FHIR is pronounced "fire".

FHIR breaks healthcare into about 150 resources, each a self-contained, modular chunk of clinical or administrative data. Rather than one giant patient record, you compose small pieces.

The resources you will meet first:

• Patient and Practitioner: who the person and clinician are.
• Encounter: a visit or admission.
• Observation: a measured value (vital sign, lab result).
• Condition: a diagnosis or problem.
• MedicationRequest and AllergyIntolerance: prescriptions and allergies.

Each resource has a defined set of elements, a stable structure, and its own URL once stored on a server. Coded elements point at the same terminologies as v2 (LOINC, SNOMED CT, ICD), so the semantic layer carries over. You model a real clinical situation by combining resources and linking them.

Here is the same patient from the previous lesson, now as a FHIR Patient resource:

{
  "resourceType": "Patient",
  "id": "100457",
  "identifier": [{
    "system": "urn:hosp-a:mrn",
    "value": "100457"
  }],
  "name": [{
    "family": "Dubois",
    "given": ["Marie", "L"]
  }],
  "gender": "female",
  "birthDate": "1982-03-04",
  "address": [{
    "city": "Lausanne",
    "postalCode": "1003",
    "country": "CH"
  }]
}

Every resource declares its resourceType and carries an id. Fields are named, not positional, so nothing depends on counting pipes. A human and a parser read it the same way. That readability is much of FHIR's appeal.

Resources stay small because they reference each other instead of nesting everything. An Observation does not embed the whole patient; it points to one:

{
  "resourceType": "Observation",
  "status": "final",
  "code": { "coding": [{
    "system": "http://loinc.org",
    "code": "2339-0",
    "display": "Glucose"
  }]},
  "subject": { "reference": "Patient/100457" },
  "valueQuantity": { "value": 5.4, "unit": "mmol/L" }
}

The subject field is a reference to Patient/100457. Follow it and you get the patient. When you need several linked resources delivered together, FHIR wraps them in a Bundle: a single resource that contains a list of others, used for search results and batch operations. References plus Bundles are how a flat set of small resources represents a rich, connected clinical picture.

FHIR resources are exchanged over a standard REST API. Every resource type sits at a predictable path, and the HTTP verb chooses the action:

Search is the workhorse: query parameters filter by patient, code, date, status, and more, and results come back as a Bundle. Because this is ordinary HTTP, standard web tooling applies, including OAuth 2.0 for authorization (the SMART on FHIR profile defines how apps get scoped access to a patient's data). Any language with an HTTP client is a FHIR client.

The flow is exactly a web API call. An app sends an HTTP GET to a FHIR server, the server authorizes the request and looks up the resource, and it returns JSON. If the resource references others, the app follows those references or asks the server to include them. Nothing here is healthcare-specific except the resource shapes.

Base FHIR resources are deliberately broad so they fit every country and use case. Real deployments constrain them with profiles: rules that mark which elements are required, which codes are allowed, and which extensions add locally needed data. A set of profiles for a purpose is packaged as an Implementation Guide (IG).

In the United States, the key IG is US Core, which defines the profiles that satisfy USCDI (the United States Core Data for Interoperability), the government-mandated minimum data set. When a US regulation says a system must expose patient data via FHIR, it effectively means US Core profiles on the relevant resources. Other regions maintain their own IGs. So "supports FHIR" is rarely enough on its own; the real question an integration engineer asks is which IG and which version.

FHIR has released several major versions. In practice, one matters most today. R4, published in 2019, is the production baseline: it is what the major EHR vendors expose in their live APIs and what US regulations target. R5 is published but, per HL7 and vendor guidance, sees limited production adoption; the major EHR platforms do not yet offer production R5 APIs, so apps that read and write real EHR data still use R4. HL7 has signaled that US Core will skip R5 and move from R4 toward the future R6.

The practical rule: build against R4 and the relevant Implementation Guide unless a specific partner requires otherwise. Knowing which version and profile you are targeting is half the job. The next lesson connects all of this, v2 and FHIR alike, through the integration engine that routes and transforms between them.