EHR API Design

What is EHR API design?

EHR API design is the work of defining how outside software reads and writes data in an electronic health record: the resources and profiles exposed, identifiers and versioning, write rules, authorization and launch context, documentation and terms, and the policy for changing the API over time. Most EHR APIs today build on HL7 FHIR R4 and US Core.

Good EHR API design treats the API as a product with its own users. The front-end team, partner developers and certification testers are all customers, and each needs predictable behavior more than a long feature list.

Which consumers will the EHR API serve?

List the consumers before designing a single endpoint, because each one needs different access patterns, scopes and limits. One API usually serves all of them through different entry points.

• Patient apps: Read access to a patient's own record, launched outside the EHR, with patient consent and revocation.
• Clinician apps: Apps launched inside the chart with the current patient and encounter as context, often needing write access.
• Backend systems: Labs, billing, scheduling and partner services that call without a user present.
• Population consumers: Analytics, payers and quality programs that need whole groups of patients at once.
• Your own front end: The EHR's screens, if you choose to build them on the same API, which forces the API to be complete.

Building your own screens on the public API is a strong design choice. It guarantees that what partners can do matches what your users can do, and it surfaces gaps long before an outside developer finds them.

How far should the API follow FHIR and US Core?

Follow FHIR R4 and US Core for every concept they cover, and extend carefully for the rest. Partners already know these standards, and certified API criteria require them.

ONC's companion guide for 45 CFR 170.315(g)(10), the standardized API criterion, requires a certified API to respond to single-patient and group requests using the adopted FHIR, US Core and Bulk Data standards, to let applications register with its authorization server, and to support SMART App Launch for authentication and authorization. For clinician access through an EHR launch, it lists capabilities including launch-ehr, context-banner, context-style and context-ehr-patient.

• US Core first: Use US Core profiles for patients, problems, medications, allergies, results, vitals, notes and the rest of USCDI.
• Extensions sparingly: Add extensions for data US Core does not carry, publish their definitions, and keep them few.
• Custom operations last: Use FHIR operations for real workflows that resources cannot express, such as a scheduling search.
• One terminology policy: Return the codes US Core requires, such as LOINC for results, and keep local codes as additional codings.

Map your internal data model to these profiles early, field by field, and record every place where the internal model holds something the profile cannot express. That gap list decides which extensions you need, and it is far easier to agree on in design than to argue about once partners are live.

How should identifiers and versions be designed?

Give every resource a stable logical id that never changes or gets reused, and carry business identifiers, such as medical record numbers, as separate identifier values with their own system. Then make versions visible so clients can detect changes and conflicts.

The FHIR R4 RESTful API defines how. The version id is carried in the ETag header, and for version-aware updates the client sends the version it last read in an If-Match header. If that version no longer matches, the server returns 412 Precondition Failed instead of updating, which stops two writers from silently overwriting each other.

• Stable ids: Never reuse an id after deletion, and never expose database sequence numbers that leak volume.
• Merged patients: Decide how a merge appears to clients, such as a link from the old Patient to the surviving one.
• History: Support reading earlier versions where clinical integrity depends on it, such as amended notes.
• Deletes: Return 410 Gone for deleted resources and 404 for unknown ones, as the specification distinguishes.

How should the API handle writes?

Treat every write as a clinical event that must be validated, attributed and safe to retry. Read APIs are forgiving; write APIs change what a clinician sees in the chart.

• Validation: Check profile conformance, required codes and references before accepting, and return an OperationOutcome that says exactly what failed.
• Attribution: Record who wrote the data, through which app and on whose behalf, using Provenance or equivalent metadata.
• Safe retries: Use conditional create or client-supplied identifiers, so a network retry does not create two orders.
• Draft versus final: Let apps write drafts or suggestions that a clinician signs, rather than final entries, where clinical review is needed.
• Scope of writes: Start with the writes partners need most, such as observations, documents and questionnaire responses, and add orders later.
• Concurrency: Require If-Match on updates to clinical resources, so stale clients cannot overwrite newer data.

Decide what happens downstream of each write. An observation written by an app may trigger alerts, appear in reports or feed decision support, and the API documentation should say so.

What should authorization support?

Authorization should support SMART App Launch for user-facing apps and a backend services flow for system-to-system calls, with scopes fine enough that each app gets only what it needs.

• Launch context: Pass the patient and encounter in context for apps launched from the chart.
• Granular scopes: Support resource-level and, where certification requires it, category-level scopes such as particular Observation categories.
• Patient revocation: Let patients see and revoke the apps they have authorized.
• Token introspection: Let resource servers and partners check whether a token is still valid.
• Backend clients: Register system clients with keys rather than shared passwords, and limit them to named scopes.

Security controls on each call, such as audit logging and encryption, belong to the HIPAA Security Rule work, and the API design should leave room for them rather than repeat them.

What must an EHR API publish?

An EHR API must publish enough for a developer to build against it without a sales call: documentation, terms, fees and a test environment. For certified APIs this is a regulatory condition, not a courtesy.

Under 45 CFR 170.404, a Certified API Developer must publish complete business and technical documentation through a publicly accessible hyperlink that anyone can reach without preconditions. It must publish all terms and conditions, including fees, restrictions and registration requirements, and describe any fees in detailed, plain language, including who pays, when and how the amount is calculated.

• Capability statement: A machine-readable list of resources, operations and search parameters supported.
• Developer guide: Authentication, launch, paging, errors and examples for each common task.
• Sandbox: A test environment with synthetic patients that behaves like production.
• Changelog: Every change with its date and whether it can break clients.
• Status and limits: Published rate limits and a status page for incidents.

Treat the documentation as part of the release. If a change ships without its documentation and changelog entry, partners learn about it from a failed call.

How do you evolve the API without breaking apps?

Evolve the API by making additive changes freely and breaking changes rarely, with notice and overlap. Apps built on your API are your customers' tools, and breaking them breaks clinical workflows.

• Additive by default: New optional fields, resources and search parameters do not break well-behaved clients.
• Breaking changes: Removing fields, changing meanings or tightening validation needs a new version and a deprecation period.
• Contract tests: Keep a suite of real partner calls that must pass before any release.
• Standards upgrades: Plan for new US Core and SMART versions, which certification requires on a schedule.

Write the deprecation policy down and publish it with the documentation: how much notice partners get, how long old and new versions run side by side, and how you will tell them. Partners plan their releases around that promise, so keep it even when an internal deadline makes it inconvenient.

EHR API design mistakes

• Internal model exposed: The API mirrors database tables, so every schema change breaks partners.
• Read only for too long: Partners build workarounds, such as screen scraping or fax, for writes the API never offered.
• No concurrency control: Two apps update the same medication list and one change is lost.
• Hidden terms: Fees and limits appear only in contracts, and developers give up before building.
• Sandbox drift: The test environment runs an older version, so apps pass testing and fail in production.
• Unbounded searches: Search endpoints without paging or required filters let one client pull a whole table and slow the API for everyone.

Each of these is cheaper to prevent in the first version than to fix after partners depend on the behavior, which is the strongest argument for an API design review before the first external app connects.

How Agnotic can help

Agnotic Technologies designs and builds EHR APIs for clients building their own clinical platforms: US Core profiles and extensions, identifier and version rules, safe write-back with validation and provenance, SMART App Launch and backend authorization, and the documentation and sandbox that partners need.

For teams heading toward certification, Agnotic plans the API against the 170.315(g)(10) requirements and the publication conditions from the start, so testing is a check rather than a rebuild.

Sources

• 45 CFR 170.404: Application programming interfaces
• ONC: Standardized API for patient and population services, 170.315(g)(10)
• HL7 FHIR R4: RESTful API