Project

General

Profile

Feature #40909

Updated by Ernesto Puerta over 4 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

Back