Translate the workflow into observable claims
Start with the sequence the clinic needs to operate, not a generic endpoint inventory. For every step, write a claim that can be observed: an authorised user can create an assignment, a completion can be retrieved once, an amendment remains distinguishable, or a failed write appears in an owned queue. Include the source of truth and maximum acceptable delay.
- Use synthetic people, assessments, responses, and identifiers only.
- Give every expected request, response, side effect, and audit event an acceptance criterion.
- Separate mandatory go-live capabilities from desirable future capabilities.
- State unsupported workflows explicitly so they are not inferred from adjacent endpoints.
Build a capability matrix with primary evidence
Record base URLs and environments, authentication flows, scopes, resources, operations, filters, pagination, concurrency controls, idempotency, rate limits, error formats, version policy, deprecation notice, audit evidence, and support arrangements. Link each row to an authoritative specification and a test result. In FHIR, compare the server's CapabilityStatement with the implementation guide and actual behavior. [1][2][3]
The API integration evidence ladder
A five-step evaluation sequence that moves from a real workflow claim to repeatable operational evidence.
- Claim
Express each required workflow outcome as an observable acceptance criterion.
- Capability
Map specifications, deployed configuration, permissions, limits, and ownership.
- Contract
Test semantics, boundaries, authorization, versioning, and audit behavior.
- Failure
Inject timeouts, duplicates, reordering, rate limits, outages, and partial results.
- Decision
Record evidence, residual risk, pilot bounds, rollback, and retest triggers.
Verify semantics, boundaries, and authorisation
Exercise valid and invalid field combinations, missing values, large but permitted payloads, terminology, time zones, pagination boundaries, stale versions, and concurrent updates. Test permissions with separate user, patient, and system contexts. SMART scopes communicate requested clinical, contextual, and identity access, while underlying server permissions can further filter or deny results. [2][4][5]
- Confirm that each role can perform only its required operations and cannot cross tenant or patient boundaries.
- Check that expired, revoked, malformed, and wrong-audience credentials fail safely.
- Verify error responses do not disclose secrets, internal details, or another person's data.
- Confirm logs and audit records identify the action and outcome without copying unnecessary health content.
Run a failure catalogue, not one outage test
Inject timeouts before and after a write, 429 rate limits, 5xx responses, malformed success bodies, delayed webhooks, duplicates, out-of-order updates, unavailable terminology, partial batch failure, and queue downtime. For each case, observe retries, duplicate protection, alerts, operator guidance, data state, and eventual reconciliation. HTTP retry safety depends on idempotent semantics or a reliable way to determine whether the original effect occurred. [6][7]
- Define a maximum retry age and what happens after it expires.
- Prove that a repeated request cannot create a second assignment or score.
- Prove that an older update cannot overwrite a newer reviewed result.
- Reconcile totals and identifiers after recovery, then document every manual repair.
Make a bounded go-live decision and keep testing
Summarise each requirement as pass, conditional pass, fail, or not tested, with evidence, owner, and expiry date. A limited pilot should cap users, data flows, and clinical settings while preserving a tested rollback. Re-run contract and failure tests when the API version, scopes, profile, terminology, infrastructure, or workflow changes.
Sources and further reading
- FHIR R4 CapabilityStatement (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official structure for declaring supported FHIR resources, operations, formats, and implementation guides.
- SMART App Launch 2.2: Scopes and Launch Context (opens in a new tab)HL7 International. Updated 2024-04-30. Accessed 2026-07-13. Official SMART scope, identity, and launch-context semantics.
- OpenAPI Specification 3.1.1 (opens in a new tab)OpenAPI Initiative. Published 2024-10-24. Accessed 2026-07-13. Official machine-readable API description standard.
- FHIR R4 Security (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official FHIR security and privacy implementation guidance.
- OWASP API Security Top 10 - 2023 (opens in a new tab)OWASP Foundation. Accessed 2026-07-13. OWASP community-maintained API security risk taxonomy for authorization, consumption, inventory, and dependent APIs.
- RFC 9110: HTTP Semantics (opens in a new tab)Internet Engineering Task Force. Accessed 2026-07-13. Internet Standard for method semantics, status codes, and retry-relevant idempotency.
- FHIR R4 RESTful API (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official FHIR interaction, conditional operation, transaction, version, and error behavior.