####TODO: Peter Monks (and anyone else who's interested!) to flesh this out based on his 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).
- 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).
- 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?
- APIs that return meta information (available API versions on this particular pod, build numbers to help with support requests, etc.)