Versioning and deprecation
How the EDFlow API and event contract are versioned: the URL major version, dated Api-Version pins, specVersion, notice periods for new enum values and event types (60 days) and breaking changes (12 months), Deprecation and Sunset headers, and host migration.
Hospital change boards plan in quarters, so EDFlow changes the contract slowly and with notice.
Four version axes
| Axis | Example | Changes when |
|---|---|---|
| URL major | /v1 | A breaking redesign becomes /v2; /v1 stays supported at least 12 months after |
Dated Api-Version | 2026-10-01 | A breaking change within v1 ships only behind a new dated version |
Document info.version | 1.4.0 | Every published change to the OpenAPI document (semver) |
Event specVersion | 1.0 | The normalized event contract, independently |
Each app is pinned to the latest dated version when created. Override per request with Api-Version; webhooks render in the endpoint's pinned version. GET /v1/meta returns the compatibility table: for each dated version, the URL major, the document versions, the event specVersion values accepted and emitted, the HL7 support-matrix version, the FHIR IG version, and its deprecation and sunset dates.
Additive changes
New endpoints, optional request fields and response fields can ship at any time. Your client must ignore unknown fields.
New enum values in responses, new webhook event types and new error codes are announced in the changelog at least 60 days before they reach customer test or live, and appear in the sandbox first. Map enums through lookup tables with a default. Endpoints subscribed to ["*"] don't receive new event types unless they opt in.
Breaking changes
At least 12 months' notice for any breaking change: a dated version, an operation or a major version. Deprecated operations send:
Deprecation: @1830297600
Sunset: Wed, 01 Mar 2028 00:00:00 GMT
Link: <…/developers/changelog#…>; rel="deprecation"After the sunset, the operation returns 410 gone. The developer portal lists your app's calls to deprecated operations. App contacts are emailed at announcement.
Host migration
Engine configurations, firewall allowlists and private_key_jwt audiences embed hosts, so API hosts don't change with branding and change only under this policy:
- Announced by email to every app contact and in the changelog at least 12 months ahead.
- During the migration both hosts serve the API, the token endpoint accepts both audiences and the issuer stays the same until the last app has moved.
- Egress IP changes have the same notice; new IPs are published in
/v1/meta90 days before first use. /v1/metatells apps still calling the old host where to go.
Related
Last updated on