...
- Summary of current Symphony's versioning approach:
- YAML file version is pinned to the current version of Symphony (e.g. 1.45, 1.46, etc.), and this mostly doesn't matter since the YAML file version isn't used for anything.
- Each API endpoint independently has a version (v1, v2, etc.)
- Currently, the Symphony engineers roll the YAML file's version for every release of Symphony. They also roll an API endpoint's version any time anything changes in that endpoint - a conservative (safe), but high effort approach.
- Endpoint Versioning vs API Suite Versioning - which is better?
- Many developer platforms seem to have standardised on API suite versioning, so that approach would adhere to the Principle of Least Surprise (as one of many potential comparative criteria).
- But the current Symphony API versioning approach doesn't do that, so there's a grandfathering problem (another potential comparative criteria).
- Best Practice from BNY Mellon - is that MAJOR version in the semantic versioning scheme is sufficient. The major version is part of the REST API base URI.
- When do versions need to change?
- That's easy: at least when a backwards compatibility breaking change is made (Symphony's current API versioning policy exceeds this requirement).
Whenever backwards-incompatible API changes are introduced, the version number should be incremented.
- Conversely, for backward-compatible changes, do not change the version number but instead include a revision header.
- So what constitutes a backwards compatibility breaking change?
- ####TODO
- Version numbers as communicators of change:
- Semantic Versioning (semver) clearly identifies how version numbers should be used to communicate change, and is already mandated for use elsewhere in the Foundation.
- However, in the API realm, consumers generally don't care about backwards compatible changes (since those don't "ripple out" to impact their code), so is semver appropriate here?
- Using version numbers in URLs forces incompatible changes to be communicated to clients and forces clients to make required changes before using the new API.
Example: https://apigateway.example.com/positions/v2/holdings
- Furthermore, using other mechanisms (conneg, media types, etc.) for versioning makes it harder to explore an API using standard HTTP clients (i.e. browsers)
- As new versions of an API are released, at least one previous version should be maintained. An old version that is still being supported can be explicitly called as in https://apigateway.example.com/positions/v1/holdings
- A platform should provide "meta APIs" that return meta information about the API (set of available API versions on this particular pod, build numbers to help with support requests, etc.)