Expand description
API versions, and telling clients when one is going away.
Two ways to version, because APIs use both. By path — /v1/users,
/v2/users — with Router::version, which is
the visible, cacheable, curl-friendly form. Or by header — X-API-Version: 2, Accept: application/vnd.example.v2+json — with VersionHeader,
for APIs that want one URL per resource forever. Either way the handler
asks req.api_version() and gets the same answer.
The other half is the lifecycle. A version is not retired by deleting it;
it is retired by telling every client, for months, that the day is coming.
RouteHandle::deprecated_at sends
Deprecation (RFC 9745) and RouteHandle::sunset
sends Sunset (RFC 8594), on every response from the route, so a client
library can log a warning its own developers will see.
Structs§
- ApiVersion
- The version a request is for, attached as an extension.
- Version
Header - Read the API version from a header.