%20(1).png)
A developer copies a FHIR code example from your health API docs. It works in sandbox. It ships to production. Three weeks later, a patient's medication list is pulling from the wrong resource, and an integration that passed every test is returning incomplete allergy data to a clinical decision support system.
This is not hypothetical. It is the pattern behind a growing number of health IT integration failures as the industry moves to FHIR-based APIs at scale.
A wrong API example in healthtech is not a typo. It is a clinical risk, a compliance liability, and a patient safety issue packaged as a documentation bug.
Healthcare APIs are no longer a niche concern. Epic alone reports 2,496 live apps using its open APIs, with 750+ no-cost APIs and interfaces generating 234 billion API transactions annually. Nearly 800 patient-facing apps exchange data through the TEFCA interoperability framework.
Those numbers mean every code example in Epic's 40+ developer playbooks reaches thousands of developers building apps that touch real patient data. A stale example does not just waste an afternoon. It propagates through an ecosystem.
FHIR, the HL7 standard that underpins modern health APIs, spans 13 modules and supports JSON, XML, and RDF formats. Its reference implementation HAPI FHIR warns developers that core objects are "expensive to instantiate" and that selecting the right FHIR version is a critical decision developers must make before writing a single line of integration code.
When your documentation points developers to the wrong version, the wrong resource, or the wrong endpoint, they build on a broken foundation.
Here is what a single bad code sample costs when it reaches health API developers.
Healthcare integrations are not weekend projects. Industry benchmarks put a typical EHR integration at 6 to 18 months and $150,000 to $500,000 (KLAS Research, EHR Integration reports, corroborated by CHIME Digital Health surveys). When a developer follows a stale code example and builds on a deprecated endpoint or an outdated resource structure, the cost is not a bug fix. It is months of rework.
The Postman 2023 State of the API Report found that 54% of developers cite documentation as the number one factor when evaluating an API. In healthtech, where switching costs are measured in six-figure integration budgets, losing a developer to a bad code sample means losing a deal you may never know about.
72% of developers have abandoned an API due to poor documentation (Postman 2023). In an industry with only a handful of credible EHR vendors, each abandoned integration is a lost partnership.
When a health API developer hits a documentation error, the first stop is your developer support channel. But healthcare API support is not a quick chat.
Each engineering-escalated support ticket costs $150 to $250 when fully loaded with engineering time (industry estimate, corroborated by DevRelCon presentations and MetricNet benchmarks). In healthtech, tickets about FHIR resource mapping, OAuth scope configuration, or SMART on FHIR launch sequences routinely require senior engineers who understand both the API and the clinical context.
A single confusing code example that generates 50 support tickets costs $7,500 to $12,500 in direct support costs. But the real cost is the engineering time diverted from building features to answering questions that accurate documentation would have prevented.
This is where health API documentation becomes existential.
The 21st Century Cures Act established information blocking penalties of up to $1,000,000 per violation (Section 4004). Information blocking means interfering with or preventing access to electronic health information. If your API documentation instructs a developer to implement an endpoint in a way that fails to return required patient data, that integration may constitute information blocking, and you are the one who wrote the instructions.
CMS Interoperability Rules (CMS-9115-F) require Medicare Advantage, Medicaid, and qualified health plan payers to provide FHIR-based Patient Access APIs. Non-compliance risks CMS certification, the regulatory approval that allows organizations to participate in federal health programs.
HIPAA adds another layer. The Security Rule requires documentation of all system access and data handling. Fines range from $100 to $50,000 per violation, up to $1.5 million per year per violation category. The average healthcare data breach costs $10.93 million, the highest of any industry (IBM Cost of a Data Breach Report, 2023). API documentation that instructs a developer to handle PHI (Protected Health Information) insecurely is a breach vector disguised as a code sample.
Wrong API docs in healthtech are not an editorial issue. They are a regulatory exposure.
Your health API docs show a Patient search example:
// Illustrative: replace fhir.example.com with your FHIR base URL
// Search for a patient by name
const response = await fetch(
'https://fhir.example.com/Patient?name=Smith',
{
headers: {
'Authorization': 'Bearer ' + accessToken,
'Accept': 'application/fhir+json'
}
}
);
const bundle = await response.json();
const patient = bundle.entry[0].resource;
console.log(patient.name[0].given[0]);But the current API requires scoped access with SMART on FHIR launch context:
// Illustrative: replace fhirBaseUrl and patientId with your values
// Search for a patient using SMART on FHIR scoped access
const response = await fetch(
`${fhirBaseUrl}/Patient?_id=${patientId}`,
{
headers: {
'Authorization': 'Bearer ' + smartAccessToken,
'Accept': 'application/fhir+json',
'X-Request-Id': crypto.randomUUID()
}
}
);
const bundle = await response.json();
if (!bundle.entry || bundle.entry.length === 0) {
throw new Error('Patient not found within authorized scope');
}Both work in a sandbox with permissive access controls. Only one works in a production environment with proper SMART on FHIR scoping. The developer who follows the first example will discover the problem when their app fails clinical validation at a health system, weeks into the integration.
These are not edge cases. They are patterns across the health API ecosystem.
FHIR version fragmentation: FHIR has gone through DSTU2, STU3, R4, and R5. Epic's documentation notes that the "App Default FHIR Version" is configurable, meaning developers must select the correct version before implementation. Code examples written for STU3 resources may compile against R4 endpoints but return different data structures, silently dropping fields that clinical applications depend on.
Sandbox-production gaps: Epic's developer documentation explicitly states that sandboxes are "for testing purposes only" and data "may be wiped or otherwise removed." Sandbox environments do not enforce production-level SMART on FHIR authorization. A code example that works in sandbox may fail in production because it never handled the real OAuth flow.
SMART on FHIR scope mismatches: The SMART on FHIR framework requires applications to request specific OAuth scopes (e.g., patient/Observation.read, patient/MedicationRequest.read). Documentation that shows a broad scope like patient/*.read may work in development but be rejected by health systems that enforce granular scope policies.
Argonaut to US Core evolution: The five largest EHR vendors collaborated on the Argonaut Project to standardize SMART on FHIR. Those early Argonaut profiles evolved into US Core profiles, but code examples referencing Argonaut-era data structures still exist across tutorials and integration guides.
Every one of these incidents shares the same root cause: the API evolved, the documentation did not.
The pattern is identical to every other industry, but the stakes make the urgency different. Code ships, docs do not update, the gap grows until a clinical application hits it.
Three things close the gap:
1. Automated review on every PR. When code changes, check if documentation references the changed FHIR resources, endpoints, or OAuth scopes. Flag stale examples before they merge. In practice, this means a CI step that scans your markdown files for references to endpoints or resource types that were modified in the current PR. If a developer changes the Patient search endpoint and three docs reference that endpoint, the PR should not merge until those docs are reviewed. In healthtech, a stale code example is not just a developer experience problem. It is a compliance risk that should block a release.
2. Version-aware documentation checks. Healthcare APIs version aggressively. Your documentation linting should know the difference between R4 and R5 resource structures, flag deprecated Argonaut-era patterns, and catch scope mismatches between examples and current authorization requirements. A lint rule that catches patient/*.read in documentation and flags it as overly broad, for example, prevents scope rejection at the health system level before the developer ever encounters it.
3. Freshness tracking with compliance context. Know which documentation pages reference endpoints or resources that have changed since the pages were last updated. Prioritize updates by clinical impact: a stale example on a medication endpoint is a higher risk than a stale example on an administrative endpoint. Track when each code example was last verified against the current API version, and surface pages that reference FHIR resources modified in the last release cycle.
If your health API docs are the first thing a developer reads when building an app that touches patient data, they need the same quality bar as the code they describe.
EkLine automates documentation review in your GitHub PR workflow, catching stale API examples, broken links, and style violations before they reach developers. See how it works.
