Application programming interface

An API is a contract between systems

The contract describes available operations, request and response formats, identifiers, authentication, errors, limits, and versions. One API may let a scheduling system create an appointment; another may expose read-only client demographics. Access to one endpoint says nothing about permission to use another.

ONC describes FHIR as an API-focused HL7 standard for representing and exchanging health information. FHIR provides structures and exchange patterns. Implementers still need compatible versions, profiles, meanings, identities, authorization, and operational testing.

Map purpose, data, and authority

For every integration, record the source system, destination, direction, purpose, data elements, legal and contractual route, permitted users, and retention. Distinguish technical access from authority to use or disclose the data.

An appointment status may mean “scheduled” in one system and “ready for billing” in another. Build a field map with definitions, allowed values, null behavior, time zones, units, code sets, and source of truth. Assign a qualified owner for clinical or billing meaning.

Authenticate, authorize, and limit access

Authentication establishes which system or user is calling. Authorization determines which actions and records that identity may access. Use narrowly scoped credentials, secure secret storage, rotation, logging, environment separation, and prompt removal when a relationship ends.

NIST SP 800-228 Update 1 provides final cloud-native API protection guidance covering risks and controls before and during runtime. It is general technical guidance rather than a healthcare compliance certificate.

Design for retries and duplicate events

Networks fail. A sender may retry after a timeout even when the first request succeeded. Define idempotency or another duplicate-control method, stable event identifiers, retry limits, dead-letter handling, and human ownership for exceptions.

Timestamps, sequence numbers, and status transitions need explicit rules. Never assume arrival order matches event order. Preserve request, response, correlation ID, system version, time, and final disposition without logging unnecessary sensitive content.

A fictional appointment feed

Theo’s practice locks a cohort of 50 appointment-change events. Forty-seven arrive with the expected client, appointment, status, and timestamp and reconcile to the source: 47 of 50, or 94%. Two time out and succeed on an idempotent retry. One contains a retired status value and moves to a hold queue.

Transport delivery is 49 of 50 after retry, while source reconciliation remains 47 of 50 until the two retried events and held event are verified. These states answer different questions. The practice keeps all three exceptions visible with owners and age.

Treat vendors and cloud data by function

If a cloud service creates, receives, maintains, or transmits ePHI on behalf of a covered entity or business associate, HHS cloud guidance explains that business-associate obligations can apply even if the vendor lacks a decryption key. Map subprocessors, support access, storage, logs, backups, incident notice, return, and deletion.

A BAA or security claim covers part of the relationship. Each regulated party still has applicable duties, and the practice must determine whether the underlying use or disclosure is permitted.

Test business outcomes and recovery

Test valid, invalid, duplicate, delayed, missing, unauthorized, and out-of-order requests. Confirm alerting, rate limits, partial failure, reconciliation, and rollback. For clinical or billing workflows, include a qualified reviewer and verify that the destination preserves the required meaning and evidence.

Define the manual path before launch. During an outage, protect safety, continue authorized critical work, queue changes carefully, and reconcile after restoration. Revalidate after API, field, credential, vendor, source-system, or workflow changes. A 200 success response confirms a technical result under that call; it cannot prove the downstream business outcome.

Ask for an integration evidence packet

Before signing, request the API documentation, supported versions, authentication method, authorization scopes, uptime and support terms, change-notice process, rate limits, error catalog, audit fields, retention, incident route, and data-return plan. Identify customer-controlled settings and every subprocessor that handles sensitive data.

For implementation, retain the approved field map, sample payloads without unnecessary sensitive data, test results, credential owner, environment inventory, release decision, and rollback steps. Give each exception queue an operational owner and a clinical or billing escalation route when meaning requires that expertise.

Production monitoring should separate availability, transport success, semantic acceptance, and downstream completion. A request can arrive while carrying an invalid payer identifier. A valid payload can wait unprocessed in a queue. Report each stage with its own numerator, denominator, clock, and source.

Set a review trigger for vendor announcements, version deprecation, changed scopes, new fields, security incidents, rising error rates, and workflow redesign. Remove unused credentials and endpoints. An undocumented connection becomes harder to secure, troubleshoot, reconcile, and retire.