FHIR, for the people who ship.
A working developer's introduction to FHIR R4. The parts of the spec you'll actually touch, the parts you can ignore until later, and the patterns that hold up once real patient data starts flowing.
The mental model.
FHIR — Fast Healthcare Interoperability Resources — is a REST-shaped specification for clinical data. Every clinical concept is a Resource. Every Resource has a stable type (Patient, MedicationRequest, Observation, Encounter…), a unique id, and a versioned history.
References between Resources are URLs. A MedicationRequest points to a Patient. An Observation points to an Encounter. This is how the graph of a patient's record gets stitched together across sources.
When you query Ayureon for a patient bundle, what you get back is a Bundle Resource — a container — with entries pointing at every other Resource we resolved for that patient.
Resources you'll actually touch.
FHIR R4 defines ~150 Resource types. In a real production retrieval flow, you'll spend most of your time on this short list.
How Bundles work.
A Bundle has a type — searchset, transaction, collection, document — and an entry array. Each entry carries one Resource plus its fullUrl, which other entries reference.
{
"resourceType": "Bundle",
"type": "searchset",
"meta": {
"lastUpdated": "2026-05-02T11:42:08Z",
"versionId": "v1.r4.2026-05"
},
"total": 47,
"entry": [
{
"fullUrl": "https://api.ayureon.com/Patient/4419-22A",
"resource": { "resourceType": "Patient", "id": "4419-22A", "...": "..." }
},
{
"fullUrl": "https://api.ayureon.com/MedicationRequest/mr-001",
"resource": {
"resourceType": "MedicationRequest",
"id": "mr-001",
"subject": { "reference": "Patient/4419-22A" },
"...": "..."
}
}
]
}References, the tricky part.
References are how Resources point at each other. They come in three shapes:
- Patient/4419-22A — a relative reference within the same server.
- https://api.ayureon.com/Patient/4419-22A — an absolute reference.
- urn:uuid:... — a logical reference used inside Bundles when resources don't have permanent server identifiers yet.
The thing nobody warns you about: references inside a Bundle often point at fullUrls within the same Bundle, not at the outside world. When you flatten a Bundle into your own data model, walk the entries first to build a fullUrl-to-resource map, then resolve references against it.
What you can mostly ignore.
FHIR has a rich extension model, a constraint language called FHIRPath, structured definitions (StructureDefinition), capability statements, and several flavors of profile including US Core, IPS, and Carin BB.
For your first six months on Ayureon, you do not need to read most of it. Pull bundles, traverse references, surface what your product needs. Come back to profiles when a specific partner requires conformance.
The real surprise.
The hard part of working with FHIR is not the spec. It's what the spec contains.
Allergies arrive five times, from five sources, with five spellings. Medication names land as free text alongside RxNorm codes that don't agree with them. Lab units shift between encounters. The same patient comes back with three different MRNs across systems.
This is the normalization, deduplication, and reconciliation layer Ayureon runs on top of every Bundle we return — so the data your application receives looks like one patient, not five fragments stapled together.
A discharge, a new prescription, a pharmacist who sees it before the patient walks in.
The Texas Community Pharmacy Interoperability Pilot is built on the FHIR mechanics covered above. Here is one end-to-end flow, by resource.
A patient is discharged from a hospital with a new prescription for apixaban (Eliquis). The patient is on a community pharmacy panel. The hospital's EHR fires an ADT A03 (discharge) message to the THSA EDEN program.
EDEN delivers the ADT to Ayureon. Ayureon queries the QHIN network for the patient's clinical summary as a FHIR R4 Bundle (resourceType: Bundle, type: searchset). The Bundle contains a Patient, an Encounter for the discharge, a MedicationRequest for the new apixaban prescription, and several DiagnosticReport resources for the labs from the admission.
The MedicationRequest has medicationCodeableConcept.coding[0].system = http://www.nlm.nih.gov/research/umls/rxnorm and code = 1364430 (apixaban 5 MG oral tablet). status = active. authoredOn = the discharge date. encounter.reference points back to the discharge Encounter — so the prescription is unambiguously tied to this admission, not to a prior visit.
Ayureon's MedRec primitive reconciles the new MedicationRequest against the patient's existing active medications — pulled from Surescripts and from the community pharmacy's own fill record. It surfaces a potential drug-drug interaction: the patient is already on a NSAID for chronic pain, which raises bleeding risk on a new anticoagulant.
The community pharmacist sees the alert in their PMS surface before the patient walks in. They call the discharging prescriber, recommend tapering the NSAID, and document the intervention. The MedicationStatement resource is updated with the new active list. The intervention itself is captured as a CarePlan resource with provenance attached — visible to the broader care team, defensible to the payer, and available for outcomes research.
This is FHIR doing the work it was built for: a Bundle that means something at the point of care, with every resource linked back to its source and every action documented in the same data model.
See FHIR in practice.
Get an API key, run your first retrieval, and walk through a real Bundle with one of our engineers.