*since they can now leave their scripts and whatnot at 3.0 for the time being.
On Fri, Aug 27, 2021 at 4:37 PM ocket 8888 <ocket8...@gmail.com> wrote: > 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 >> >
