The dug API deprecation and sunset policy
Nothing is deprecated today, and the absence of a Deprecation header is how you can tell. Checking for one on each response is enough. Nothing here disappears without it, and you don’t need to watch this page to stay ahead of a removal.
- Deprecation
- the day it became deprecated, as an HTTP date (RFC 9745)
- Sunset
- the day it stops answering, as an HTTP date (RFC 8594)
- Link
- rel="deprecation", pointing at what to read
- where
- on the deprecated route’s own responses, not only here
The signal travels with the thing being deprecated. A client that reads response headers already has everything it needs and never has to poll a changelog.
- notice
- at least 180 days between the two dates
- replacement
- ships under /v2/ before either date is set
- order
- new surface first, then Deprecation, then Sunset
- after sunset
- 410 Gone, with a Link to the replacement
A replacement existing before the clock starts is the part that matters. Six months of warning isn’t much use if there’s nothing to migrate to for five of them.
The paths are unversioned and additive. These happen without notice, so parse defensively and ignore what you don’t recognise:
- new commands
- a new route appears, nothing existing moves
- new fields
- added to the envelope or to a block's props
- new blocks
- a screen grows a component you haven’t seen
- new notes
- provenance and limits get more specific
A change that would break an existing caller isn’t one of these. It ships under a new path prefix, and the old one follows the timeline above.
Every response carries X-API-Version, naming the contract that produced it. Send the same header to pin it. Ask for a version this surface doesn’t serve and you get error.code unsupported_version, not a silent answer from a different one.