API Versioning
How the Diveity API evolves — what changes break clients and how we communicate them.
Backward-compatibility rules
These rules describe what is safe and what is breaking on every endpoint of /api/v1.
Response fields
- Adding a field is non-breaking — clients ignore unknown fields.
- Removing a field is breaking — requires a new API version.
- Renaming a field is breaking — requires a new API version.
- Changing a field's type (e.g. string → number) is breaking — requires a new API version.
Query parameters
- Adding an OPTIONAL query parameter is non-breaking.
- Removing an optional query parameter is breaking — clients depending on it lose functionality silently.
Deprecation policy
When we ship a new major API version, the previous version enters a documented sunset path.
- Minimum 6 months notice between deprecation announcement and end-of-life.
- During the deprecation window, every response carries the RFC 9745 Deprecation header (?1) and the RFC 8594 Sunset header (HTTP-date of EOL).
- 30 days before sunset, brownouts kick in: a small fraction of requests return 503 Service Unavailable to surface lingering integrations. The fraction ramps from 0% to 25% across the window.
- Developers whose API keys hit a deprecated version in the prior 30 days are emailed once per major version transition.
- After the sunset date the version is removed; requests to it return 404.