Feature #40909
Updated by Ernesto Puerta almost 5 years ago
In order to get an stable API we can either:
- Freeze existing API and allow only additive modifications (i.e.: new Resources, and extensions to the existing Resources under the assumption they don't break anything backwards).
- Use versioning for API.
The first approach (freezing API + additive changes) results in an ever growing API, where no refactoring is possible and the impact of changes is hard to determine.
Most APIs rely on versioning:
* URI versioning: @/api/v2/resource@
* Query string versioning: @/api/resource?version=2@
* HTTP Headers:
** Custom Header: @X-Dashboard-Version: 2@
** MIME-compliant Vendor-specific Media Definition (VND): @Accept: application/vnd.ceph.dashboard.v1+json@
**There is NO need to increment version on ANY change, but only in breaking ones**.
References:
"Versioning":https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#versioning-a-restful-web-api