Versioning and deprecation

Status: active Owner: Platform team Last updated: 2026-05-25

This document explains how Vendu signals deprecations on the public HTTP API and how much advance notice clients can rely on.

Headers

A deprecated endpoint, query parameter, or response field is announced through HTTP headers per RFC 8594 + the IETF deprecation draft:

Deprecation: true
Sunset: Sat, 31 Jul 2026 23:59:59 GMT
Link: <https://docs.vendu.app/api/migration/x>; rel="deprecation"
Link: <https://docs.vendu.app/api/x-replacement>; rel="successor-version"
Warning: 299 - "Migrate to <new path> before the Sunset date."

Deprecation: true — the response was produced by something we intend to remove.
Sunset — the earliest date when the endpoint may return 410 Gone (or 400 for a deprecated query param). Always in IMF-fixdate / RFC 7231 form.
Link rel="successor-version" — canonical replacement URL.
Link rel="deprecation" — migration write-up (the diff between old and new behaviour).
Warning: 299 — human-readable hint for log scrapers / SDKs.

Notice window

Minimum 90 days between the first Sunset header and the date the deprecated path can return 410. We aim for 180 days for breaking changes that need a migration script on the client side.
We email tenants who actually used the deprecated path at T-90, T-30, and T-7 days. The audit log (outbound_webhook_attempts, api_key_usage once T-9 lands) is the source of truth for "actually used".
A Sunset date may be extended but never shortened.

What can be deprecated

Surface	Mechanism
Whole endpoint	Wrap route handler with `wrapDeprecated(handler, opts)`.
Query parameter (e.g. `?offset=`)	Decorate the response with `deprecatedParam(res, present, opts)`.
Response field	Add a `Warning: 299` + document the replacement. The field is removed only after the Sunset date.
Whole API version	New version is published in parallel; `Deprecation: true` on every v1 response 6+ months before sunset.

Active deprecations

Surface	Sunset	Replacement
`?offset=` pagination	2026-07-31	Cursor pagination (`?cursor=`) — migration guide

References

RFC 8594 — The Sunset HTTP Header Field
draft-ietf-httpapi-deprecation-header — The Deprecation HTTP Header
RFC 7234 §5.5 — The Warning Header Field