####TODO: Peter Monks (and anyone else who's interested!) to flesh this out based on prior experience. Topics may include:

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.)

Browser not supported