Docs · Concepts
Versioning and deprecation
What Folio promises about changes within /v1, how deprecations are announced and how webhook payload versions work.
- Everything is under
/v1. Within/v1Folio only adds: new optional fields, new endpoints, new enum values and new error codes. Clients must ignore fields and enum values they do not know. - Removing something, or changing what it means, is a breaking change and ships as a new version path.
info.versionin the OpenAPI document is the build version of the service that produced it. Each guide on this site shows the version it was last checked against.- Webhook payloads carry an API version (the
folio-api-versionheader). A new payload shape gets a new version, and an endpoint keeps receiving the version it was created with until you change it. - The booth contract is versioned separately by
X-Folio-Device-Contract. See booth devices.
Deprecation#
Before anything is removed, Folio announces it at least 12 months ahead. While an operation is deprecated, every response carries:
| Header | Meaning |
|---|---|
Deprecation | When it was deprecated (RFC 9745). |
Sunset | When it stops working (RFC 8594). |
Link with rel="successor-version" | Where to go instead, when there is one. |
The OpenAPI document marks the operation deprecated: true, and the changelog records it. Log these headers so you notice. No operation is deprecated today.
Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.