HL7 FHIR Integration Tutorial: Step-by-Step Developer Guide

const response = await fetch(
 `${baseUrl}/Patient/${patientId}`,
 { headers: { "Accept": "application/fhir+json" } }
);
const patient = await response.json();
console.log(`Name: ${patient.name[0].given[0]} ${patient.name[0].family}`);

javascript

const params = new URLSearchParams({
 patient: `Patient/${patientId}`,
 _include: "MedicationRequest:requester",
 status: "active"
});

const response = await fetch(
 `${baseUrl}/MedicationRequest?${params}`,
 { headers: { "Accept": "application/fhir+json" } }
);
const bundle = await response.json();

bundle.entry.forEach(entry => {
 if (entry.resource.resourceType === "MedicationRequest") {
 const med = entry.resource.medicationCodeableConcept?.coding?.[0]?.display;
 console.log(`Medication: ${med}`);
 }
});

---

Testing and Validation

Resource Validation

Validate your FHIR resources against the specification and relevant implementation guides before sending them to production servers.

FHIR Validator — https://validator.fhir.org — Paste JSON/XML and validate against R4 base spec or specific IGs (US Core, USCDI).

HAPI FHIR Validator — Available as a Java library for automated validation in CI/CD pipelines.

Conformance Testing

Touchstone — Automated conformance testing against specific IGs. Useful for verifying that your FHIR server or client implementation meets US Core, USCDI, or other required profiles.

EHR Sandbox Testing

Before integrating with a production EHR, test extensively against the vendor’s sandbox. Epic’s sandbox, Oracle Health’s test environment, and athenahealth’s developer portal all provide synthetic patient data and simulated EHR behavior.

The sandbox is not identical to production — vendor-specific quirks, custom extensions, and undocumented behaviors may surface only in production. Plan for a testing phase against the production environment (with test patients) before go-live.

---

Common Integration Pitfalls

Assuming FHIR implementations are identical across EHRs. Epic’s FHIR implementation, Oracle Health’s FHIR implementation, and athenahealth’s FHIR implementation all conform to FHIR R4 but differ in resource coverage, search parameter support, custom extensions, and error handling. Test against each specific EHR you need to support.

Ignoring pagination. FHIR search results are paginated. If you only read the first page, you miss data. Always follow the next link in the Bundle until there are no more pages.

Hardcoding terminology codes. LOINC codes, SNOMED codes, and RxNorm codes should come from configuration or terminology services — not hardcoded strings scattered through your codebase. Codes change and expand over time.

Not handling missing data. FHIR resources frequently have optional elements that may not be populated. Robust code must handle missing elements gracefully — not crash on a null reference.

Skipping SMART on FHIR. Building custom authentication instead of using SMART on FHIR means your app cannot launch from within EHRs and will not meet ONC certification requirements. Use the standard.

Not planning for rate limits. EHR FHIR APIs impose rate limits. Bulk operations and aggressive polling will get throttled. Use Bulk Data Access for large dataset retrieval and implement exponential backoff for rate limit responses.

Need Help with FHIR Integration? Building a FHIR integration with Epic, Oracle Health, or athenahealth? Schedule a free consultation with our integration architects. Talk to Our Integration Team →

---

Related Resources:

• Healthcare Integration Guide: HL7, FHIR & Mirth Connect
• FHIR API Development Services
• Mirth Connect Integration Services
• Epic EHR Integration Guide (Blog)
• Healthcare Interoperability Explained (Blog)
• Healthcare API Security Best Practices (Blog)
• EHR/EMR Development & Integration
• EHR Integration Cost Guide
• FHIR Readiness Assessment
• HIPAA Compliance Guide
• Case Study: Mirth Connect Migration
• Free Consultation