Versioning
At the end of this guide your app knows what can change under it and how it will learn about a retirement.
The version is in the path
Every request goes to /v1. Every response carries Shiftly-Version: v1. There is one version today.
What can change within a version
Within v1, Shiftly may add things: new resources, new operations, new fields on existing records, new event types, new query parameters and new error codes. Write your app so that an unknown field, event type or code is ignored rather than treated as a fault.
Within v1, Shiftly will not remove or rename a field, change a field's type, change the meaning of an existing error code, or remove an operation. Each of those is a breaking change and ships under a new version.
When a version retires
A new version runs beside the old one for at least 12 months. During that time, responses on the old version announce the retirement with two headers: Deprecation, carrying the unix time the version was deprecated, and Sunset, carrying the date it stops answering. Log a warning when you first see them.
Shiftly-Version: v1
Deprecation: @1790380800
Sunset: Fri, 22 Oct 2027 00:00:00 GMTChanges are listed on the Changelog, tagged Added, Changed or Deprecated, and the machine-readable definition at /openapi.json is regenerated with every release.