Guides
Versioning and deprecation
What stays the same within v1, what can arrive at any time, and how a breaking change is announced at least 12 months before it stops working.
What stays the same within v1
This reference describes /v1 at version 1.0.0, and /v1 is stable. Within /v1, paths, parameters and response fields keep their names, types and meaning, and an optional parameter stays optional. New endpoints, optional parameters, response fields, headers and enum values can arrive at any time, so read what you recognise and ignore the rest.
Notice before a breaking change
When something in /v1 has to change in a way that could break an integration, we announce it at least 12 months before it stops working. From the day of the announcement, every response it affects carries three headers:
- Deprecation
When it was deprecated:
@and Unix seconds (RFC 9745), e.g.@1793869200 - Sunset
When it stops working: an HTTP date (RFC 8594), e.g.
Fri, 05 Nov 2027 09:00:00 GMT, at least 12 months afterDeprecation - Link
<url>; rel="deprecation": the page that describes the change and what replaces it
The headers in a response
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1793869200
Sunset: Fri, 05 Nov 2027 09:00:00 GMT
Link: <https://www.wambesha.com/developers/docs/v1/versioning>; rel="deprecation"Where changes are announced
The same day, /v1/changelog carries the announcement and this reference marks the operation deprecated. Nothing in /v1 is deprecated today, so no response carries these headers yet. The changelog on this site shows the same entries /v1/changelog answers.