...
- 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 useelsewhere inthe 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?
Suggested: that the MAJOR version in the semantic versioning scheme is sufficient. The major version is part of the REST API base URI. Precede the version number with the letter “v”, for example, “v1”.
- Whenever backwards-incompatible API changes are introduced, the version number should be incremented. Conversely, for backwards-compatible changes, do not change the version number, but instead include a revision header.
- 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
- APIs that return meta information (available API versions on this particular pod, build numbers to help with support requests, etc.)
- 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
- in https://apigateway.example.com/positions/v1/holdings
- APIs that return meta information (available API versions on this particular pod, build numbers to help with support requests, etc.)