Deprecation policy
Two sentences, and we intend to be held to them.
No breaking changes are introduced within a major version. A major version is supported for 36 months after its successor reaches general availability.
What counts as a breaking change
- Removing or renaming an endpoint, field or enumeration value
- Changing the type or semantics of an existing field
- Making an optional request parameter required
- Changing a default value in a way that alters behaviour
- Tightening validation such that a previously accepted request is rejected
What does not
- Adding a new endpoint, optional parameter or response field
- Adding a new enumeration value to a field documented as extensible
- Fixing behaviour that contradicts the documentation (we will announce it)
- Performance and rate-limit changes in your favour
Current support windows
| Version | GA | Superseded | Support ends | Status |
|---|---|---|---|---|
| ATLAS v3 | 12 September 2023 | — | — | Current |
| ATLAS v2 | 4 March 2021 | 12 September 2023 | 12 September 2026 | Supported, deprecated |
| ATLAS v1 | 18 June 2019 | 4 March 2021 | 4 March 2024 | Retired |
Why it is dull
A deprecation policy is a promise made to people deciding whether to build something expensive on top of you, and the only useful property of such a promise is that it is simple enough to verify. The cost is real: maintaining v2 for three years constrains what we can change in the shared layers underneath, and there is a recurring internal argument about accelerating the end date.
We have not accelerated it and I do not expect to. A customer who built an integration in 2023 on the strength of a written commitment should not discover that commitments are negotiable when they become inconvenient for us. The longer argument.
How you are told
Deprecation is announced by e-mail to tenancy administrators, on
status.terravek.com, in the
changelog, and via a Deprecation and
Sunset header on affected endpoints, at least 36 months before support ends.