Re: Proposal: stable vs unstable TO API versions

["Frey, Taylor" <Ta...@comcast.com.INVALID>]

My two cents:

+1

As a consumer, I tend to love a Ron Popeil (“Set it and forget it”) style of consumption. Stability is king, and I definitely prefer to spend as little amount of time as possible dealing with changes I may never asked for or needed. There are other areas to focus resources (not quite Broken Window Fallacy territory, but similar parallels could be drawn).

As a developer, I prefer to “roll forward”. The technology landscape is moving around us whether we want to sit still or not. Beyond the feature development of our own product, there are constant environmental changes. Hardware and infrastructure is upgraded, OS changes, libraries are patched, APIs evolve. The 2nd law of Thermodynamics applied to software.

It appears we are referring to TO specifically when talking about API versioning, but this could apply to anything that is providing an API. Traffic Monitor and Traffic Router, for example, could have their APIs versioned as well. It seems the greatest benefit we can gain out of the declaration of an unstable API is decoupling ATC versions and releases from API versions.

I think, in general, I’m in favor of being able to release an unstable/in-development/beta API. All we would need to do is figure out how best to be explicit in that understanding. I think I’d prefer that it continues with a version number (/api/6.x) rather than unstable (/api/unstable), but I fear that documentation alone may not be sufficient in conveying that state. Perhaps something in the response to signify that this may change? I’m not sure.

Taylor

On 2021/08/27 21:19:18, Rawlin Peters <r....@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>
>