A Developer's Starting Point for FHIR

David Hay's latest guide distills FHIR into its essential concepts. Here's what it means for developers building healthcare apps today.

David Hay, an HL7 Fellow and creator of clinFHIR, recently published "FHIR: The Important Bits". It's a concise overview of the core concepts every developer needs before writing their first line of FHIR code, and one of the best starting points we've seen for newcomers to the standard. Worth reading in full.

This post highlights the key takeaways from David's guide and shows where FHIRfly fits into the picture once you're ready to start building.

Resources Are the Building Blocks

FHIR models healthcare data as roughly 140 interconnected Resources: Patient, Observation, Condition, Medication, and so on. Each resource has a defined structure (the "type") and actual instances carrying real data.

As David puts it, understanding the difference between a resource type and a resource instance is fundamental. The type is the cookie cutter; the instance is the cookie.

The critical insight: resources reference each other to form graphs. A Patient resource is referenced by Condition, Observation, and MedicationRequest resources. David calls this "THE most important thing to get your head around about FHIR," and we agree. Every FHIR integration you build will involve traversing these references.

Terminology Is Where Theory Meets Reality

David's section on terminology deserves special attention. FHIR uses coding systems like SNOMED CT, LOINC, and ICD to give clinical data precise, computable meaning. The three key data types (code, Coding, and CodeableConcept) let resources reference these systems at different levels of specificity.

This is where many developers hit their first real obstacle. The spec tells you how coded data is structured, but actually working with these terminologies (searching codes, validating bindings, mapping between systems) requires access to the underlying data.

FHIRfly provides exactly this layer. Our terminology APIs give you real-time access to:

• ICD-10 codes for diagnoses and procedures
• SNOMED CT for clinical findings and concepts
• LOINC for laboratory and clinical observations
• RxNorm and NDC for medications
• CVX/MVX for immunizations
• NPI for provider lookup

Instead of maintaining local copies of these code systems or scraping government databases, you can query them through a clean REST API with daily updates.

Exchange Patterns: Know Your Options

David covers four exchange mechanisms: RESTful API, Messaging, Documents, and Operations. For most developers building modern applications, the RESTful API pattern will be your primary integration path. It's the pattern that Patient Access APIs (like CMS Blue Button) use, and it's what most EHR vendors expose.

When you're building against a FHIR server's REST API, you'll need reliable terminology data to validate what you receive. A Condition resource with an ICD-10 code isn't useful unless you can resolve that code to a human-readable description, verify it's active, and check whether it maps to a required ValueSet.

import { FHIRfly } from '@fhirfly-io/terminology';

const client = new FHIRfly({ apiKey: process.env.FHIRFLY_API_KEY });

// Resolve an ICD-10 code from a FHIR Condition resource
const result = await client.icd10.lookup('E11.65');
// => { code: 'E11.65', display: 'Type 2 diabetes mellitus with hyperglycemia', ... }

// Search across code systems
const codes = await client.icd10.search('diabetes type 2');

Profiling and Implementation Guides

David's overview of profiling and Implementation Guides (IGs) is essential reading. FHIR resources are intentionally broad, and profiling narrows them for specific use cases. IGs like US Core, SMART App Launch, and the International Patient Summary define exactly which fields are required, what terminologies to use, and how resources should relate to each other.

This is where terminology validation becomes critical. An IG might require that Condition resources use ICD-10-CM codes with a binding strength of "required," meaning your application must use codes from that specific ValueSet or the data isn't conformant.

Where to Go From Here

If you're new to FHIR, start with David's full article. It covers everything from JSON representation to Bundle resources to the community resources at chat.fhir.org. His clinFHIR tools are also excellent for visualizing how resources connect.

When you're ready to build, FHIRfly's free tier gives you immediate access to the terminology data you'll need. No credit card, no sales call. Just an API key and the SDK or direct REST calls.

Key Takeaways

• FHIR models healthcare data as interconnected Resources, and understanding resource references is foundational
• Terminology (SNOMED, LOINC, ICD-10) gives clinical data computable meaning, but working with these systems requires tooling beyond the spec itself
• Implementation Guides constrain FHIR for specific use cases and often mandate specific code systems
• David Hay's guide is one of the best introductions available. Read it here.