Just catching up on this thread. I'm +1 on the stable vs unstable versioning
thing (having gone through writing a new API version for the role and perms
recently, and encountering the pains of it). I'm also +1 for Brennan's idea of
adding a config option to disable using unstable routes, or prefixing the
routes with "unstable" to make it very clear to the users that it is a risk
that they are taking.
-- Srijeet
On 8/27/21, 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://urldefense.com/v3/__https://github.com/apache/trafficcontrol/pull/4708__;!!CQl3mcHX2A!XtyCtE8_H3-0xxF6ztzkBFp8UYdKj0OYf9VwAp__fMt6i0GXr0ZbY04nf2eCa9jXOxcRDfxY$
)
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
