Policy
API Change Management
How Medicus classifies and communicates changes to our APIs, and the minimum notice you can expect before a change reaches your integration.
Types of API change
| Type | Examples | Minimum notice | What we also provide |
|---|---|---|---|
| Change requiring a software update (any variation to an API interface that requires you to update your software) | Adding a new required request field or header (existing calls keep working during a transition window); introducing a new authentication mechanism alongside the old one, with the old one time-limited; publishing a new API version that you're expected to migrate to, while the previous version stays live; tightening a rate limit or pagination default; adding a new enum value well-behaved clients should handle; deprecating a field or endpoint with a future removal date (the removal itself is a breaking change, see below) | Not less than 60 days prior written notice | Sufficient technical detail, including updated specifications and, where available, access to a sandbox or test environment, to assess and plan the update |
| Material or breaking change (one that would prevent your application from continuing to function without modification) | Changing the shape of a response; renaming, removing or relocating a field you read; changing a data type or format; removing an endpoint, or changing its URL path or HTTP method; making a previously optional request field mandatory with no transition window; changing HTTP status codes or error codes you branch on; removing or changing the meaning of an existing enum value; any authentication change that invalidates existing credentials or flows immediately | Not less than 90 days notice | As above |
| Emergency change (strictly necessary to address an imminent security threat, vulnerability, or a requirement of applicable law) | Emergency patch to close an actively exploited vulnerability (for example, rotating a compromised signing key or forcibly invalidating leaked credentials); immediately disabling a deprecated TLS version or cipher suite in response to a disclosed exploit; changing data handling or retention behaviour to comply with a new legal or regulatory requirement with a statutory deadline | As much notice as is reasonably practicable in the circumstances | As above, so far as practicable |
| Material modification (a significant new capability or a change to commercial or licensing terms) | Adding a significant new capability to an existing service (for example, a new clinical data type or workflow); changing the commercial or licensing terms tied to using a feature (this may require you to accept further terms) | At least 90 days advance written notice | Acceptance of further terms may apply |
How we communicate changes
If a change requires notice, we notify all affected partners by Slack or email. The notice date starts the clock for the applicable minimum notice period above. The change is then held until the agreed date, and we remind you again shortly before it's released.
If you're not sure which category a planned or announced change falls into, or you need more detail to plan an update, contact partners@medicus.health.