API Versioning Model

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