Deprecation policy
What a version in the path promises, how a change is announced before it lands, and what counts as breaking. Nothing is deprecated today: v1 is the first and current version.
The version lives in the path
The major version is the first segment after /api, so /api/v1 is a contract and not a suggestion. Adding a field, adding an endpoint, or adding a new allowed value to an existing enum is not a breaking change and ships in place. Removing or renaming a field, changing a field's type, removing an endpoint, or requiring a new field is breaking, and ships as a new major version alongside the old one.
Notice before a retirement
A version is announced as deprecated at least 90 days before it is retired, and stays available for at least 12 months after its successor ships. Whichever is longer wins. The notice appears in this page, in the OpenAPI document, and in the response headers below, so a client that reads none of the prose still has time.
The headers that carry the signal
Every response carries X-Wuandkin-API-Version, so a client can log the version it actually reached. Once a version is deprecated, its responses carry Deprecation: true and a Sunset header with the HTTP date it will stop answering, for the whole notice period. A retired version stops answering and a request to it is a 404 problem document with code not_found.
What to do when a version is announced
Move to the current version before the sunset date. The read endpoints are the same resource at the same shape, so for most clients it is a change to the base path. If a migration is not obvious, write to the address below and it will be explained.
Nothing is deprecated today
v1 is the current version and no successor is announced. If that changes, this page changes first.