A stability level is a named API version designation that communicates how the API may change and how much migration effort consumers should expect. Clear guarantees help consumers plan updates and give providers a way to collect feedback while evolving the API. section 4.11.2 section 4.9.3
Common stability policies distinguish versions by their tolerance for change:
- Alpha permits rapid iteration and breaking changes for known users who tolerate frequent change. section 4.11.2
- Beta is feature complete and publicly testable, should be as stable as possible, and must provide a reasonable deprecation period when breaking changes occur. section 4.11.2
- Stable is fully supported and avoids breaking changes except when security or regulatory requirements demand them. section 4.11.2
- Organizations may define different labels: Ghost uses Experimental for actively changing versions, Stable for forward-compatible changes, and Deprecated for versions scheduled for removal. section 4.11.2
Path-based stability identifiers
Shopify combines a dated API version with an unstable preview path: GET /admin/api/unstable/products. The unstable version may contain breaking changes, and changes are not guaranteed to ship. Snyk combines a calendar version with a stability suffix: 2023-03-03~experimental, 2023-03-03~beta, and the unsuffixed 2023-03-03 production version. section 4.9.3
Treat stability as part of the product interface, not only as an implementation choice. A useful scheme reduces consumer uncertainty and cognitive load, makes the promise obvious, and avoids shifting unnecessary migration costs onto consumers. Document the policy clearly on the developer portal. section 4.11.2 section 4.9.3
