DEVELOPER

API Catalog

Use versioned REST/FHIR interfaces with explicit authentication, idempotency where required, typed errors and correlation for operational support.

01 / CONCEPT

Integration contract

Contract

Method, media type, required scope, schema/profile and version are explicit.

Reliability

Use idempotency for retryable creates where supported and bounded retry only for recoverable conditions.

Errors

Distinguish validation, authentication, authorization, conflict, rate limit and dependency failures.

Correlation

Propagate request/correlation identifiers without placing sensitive clinical data in logs.

02 / WORKFLOW

From sandbox to evidence

01Select API/resource
02Confirm scope and schema
03Send synthetic request
04Handle success and typed error
05Correlate in integration logs
06Promote only after recovery testing

03 / EXAMPLE

Create telehealth appointment / retrieve DiagnosticReport

cURL / pseudocode

POST /fhir/Appointment  # synthetic appointment
GET /fhir/DiagnosticReport?subject=Patient/synthetic-001

04 / SECURITY & PRODUCTION

Production is an evidence decision

API integration must demonstrate idempotency where required, typed error handling, bounded retry, correlation and dependency-failure recovery before production.

EXAMPLE CONTRACTS

Read the contract before writing the client

These are synthetic examples for documentation structure; they are not claims that a named production endpoint is currently published.

Create Observation · EXAMPLE

POST /fhir/Observation · OAuth scope: observation.write · application/fhir+json · idempotency key where the deployment contract supports retryable create.

Read DiagnosticReport · EXAMPLE

GET /fhir/DiagnosticReport?subject=Patient/{id} · scoped read access · explicit pagination/filter behavior and OperationOutcome-style error diagnostics.

Webhook event · EXAMPLE

Signed callback with delivery/event identifier, timestamp and correlation; consumers acknowledge quickly and deduplicate before asynchronous processing.

Typed failure

400 validation_error · 401 invalid_token · 403 insufficient_scope · 409 conflict where applicable · 429 rate_limited; dependency errors remain distinguishable from client errors.