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** (from "[ref]":https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#123-definition-of-a-breaking-change): * Removing or renaming APIs or API parameters * Changes in behavior for an existing API (e.g.: changing defaults) * Changes in Error Codes and Fault Contracts * Anything that would violate the Principle of Least Astonishment ones**. References: "Versioning":https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#versioning-a-restful-web-api