Another possibility is leaving our current API versions as-is and making a 5.0 that is "unstable" while 4.0 becomes our new "stable". I think that would be the easiest path forward for development, and whatever infrastructure was already anticipating an upgrade. Though making 4.0 unstable would mean less work for consumers of the API since they now can leave their scripts and whatnot at 4.0 for the time being. I'd be +1 for either - choosing between the two I'd favor 5.0, but if we can't agree to do that I'm fine dropping it.
I'm still not exactly sold on Cache Config Snapshots, but that's not really what this is about. I don't think, from an API consumer's perspective this really changes much (which is sort of the point). When API versions are under development, the policy of a consumer is to not acknowledge the version's existence. That's the same thing that's happening here, just that we no longer let that stop us from cutting ATC releases (which actually alleviates much of my concern about a versioned API from back in the day). If it's really extremely important that consumers not only choose not to use an API that is documented as unstable, we could do all sorts of things to make using it harder until it's stable. A configuration option could disallow it entirely, or a 'b' could be appended to "beta" API versions e.g. /api/5.0b/servers, or it could even just be served as "unstable" or something like e.g. /api/unstable/servers to make it harder to accidentally put in the wrong version number, we could add a warning alert to all endpoints (that can return alerts) that warns that the API version being used is unstable, or add a "Warning" HTTP header so that even endpoints that don't support alerts are covered (although no known clients of the API check for that header). On Fri, Aug 27, 2021 at 3:19 PM Rawlin Peters <raw...@apache.org> wrote: > Hey folks, > > I'd like to propose that we start moving towards a TO API development > model where we consider the latest major version of the API > "unstable," while the 2nd latest major version is considered "stable." > What that means is that we would be free to make breaking changes to > the "unstable" version, while the "stable" version would maintain > backwards-compatibility. Eventually, once we feel that the latest > version of the TO API has stabilized, we will declare it "stable" and > deprecate the old stable version. > > I see multiple benefits to this: > 1. reduce the number of major API versions developers need to support, > making it easier to add new features > 2. developers can make incremental changes (breaking and non-breaking) > to the unstable API version in every release without having to > introduce new major or minor versions, making the resulting API much > better overall once it is stabilized > 3. reduce the number of unnecessary client upgrades, where the API > version changed but none of the routes the client uses were actually > changed > 4. clients that don't need the latest API features don't have to upgrade > 5. helps us release more frequently, because we aren't slowed down by > adding unnecessary code for a new TO API major/minor version with > every release > 6. gives us more flexibility in what features need to be completed > before we cut a release (because they'd be targeting the unstable API > anyways, we can cut a release without causing a bunch of re-work for > new features that missed the API version bus) > > Alas, all good things come at a price. For clients that need to use > the unstable version of the TO API (like Traffic Portal), their > upgrades may need to be closely coordinated with the Traffic Ops > upgrade. For TP, this is nothing new, because it is generally always > upgraded at the same time as TO. However, for other components that > may want to use the unstable API (e.g. `t3c`), this means certain > upgrades (not all, mind you, only those where a route the component > uses is actually broken) would have to be closely coordinated with > Traffic Ops. That said, for `t3c` at least, moving forward with Cache > Config Snapshots (https://github.com/apache/trafficcontrol/pull/4708) > would greatly alleviate that concern, since the snapshot route would > be kept backwards-compatible. > > Please let me know what you think of this proposal. If we can come to > a consensus on this, we may be able to declare TO API 3.0 "stable" and > 4.0 "unstable," meaning we can avoid a potential 5.0 API version in > whatever release comes after ATC 6.0. > > - Rawlin >
