Getting Started with FHIR R4: A Developer's Practical Guide

What is FHIR R4?

HL7 FHIR (Fast Healthcare Interoperability Resources) R4 is the current normative release of the FHIR standard. It defines a RESTful API, a set of resource types (Patient, Observation, MedicationRequest, etc.), and a common format for exchanging healthcare data between systems.

Setting Up Your First FHIR Server

The quickest path to a working FHIR R4 server is HAPI FHIR — the most widely deployed open-source implementation. Add it to your Spring Boot project:

<dependency>
  <groupId>ca.uhn.hapi.fhir</groupId>
  <artifactId>hapi-fhir-spring-boot-starter</artifactId>
  <version>7.4.0</version>
</dependency>

HAPI auto-configures a JPA-backed FHIR server at /fhir with a full REST API, capability statement, and validation support out of the box.

Core Resource Types to Know

FHIR R4 defines over 140 resource types, but most healthcare applications work with a small core set:

• Patient — demographics, identifiers, contact details
• Observation — lab results, vitals, social history
• Condition — diagnoses and problem list entries
• MedicationRequest — prescriptions and medication orders
• Encounter — visits, admissions, appointments
• DocumentReference — clinical notes, CDA documents

RESTful Operations

FHIR uses standard HTTP verbs against resource endpoints. A read operation looks like:

GET /fhir/Patient/123
Accept: application/fhir+json

Search uses query parameters defined by each resource type:

GET /fhir/Observation?patient=123&code=85354-9&_sort=-date&_count=10

Search Parameters

Every resource type defines a set of search parameters. The most important ones are common across all resources: _id, _lastUpdated, _count, _sort, and _include for eager-loading referenced resources.

Conformance and Profiles

A CapabilityStatement at GET /fhir/metadata tells clients which resources and operations your server supports. US Core profiles add constraints on top of base FHIR — for example, requiring that a Patient have at least one identifier and a gender. Validate against profiles using HAPI's validator:

FhirValidator validator = ctx.newValidator();
validator.registerValidatorModule(new FhirInstanceValidator(ctx));
ValidationResult result = validator.validateWithResult(patient);

Next Steps

Once your server is running, the next step is implementing SMART on FHIR so external applications can launch and access it securely. See our Smart on FHIR App Launch guide for a step-by-step walkthrough.

Have questions about implementing this in your healthcare platform? Get in touch with the Akhester team.