-1 on syncing the TO API version to the ATC version. In theory, we could have ATC releases that don't even change the TO API at all (I might be dreaming here), so revving the TO API version in those releases wouldn't make sense. It would definitely be easier to remember which version of ATC introduced which TO API version if they matched, but, unfortunately, that is just something we have to remember when dealing with versioned APIs.
> All good points but also consider this, ATC is version 5.x, for example, so > all the components are version 5.x, right? Not necessarily. If we were more disciplined about it, we could give each component its own version and maintain a version compatibility table. Also, we have some components (like Traffic Stats) which go many ATC releases without actually changing at all, but their rpm version is still updated. Because the rpm version is updated, it causes the outside observer to think that the component was actually changed and that they should upgrade. However, upgrading is actually unnecessary work in those cases. Continuing along these lines, we could give TO its own version that mostly matched its latest API version. For example, the TO API version is currently 4.0. We could simply declare that the TO version is 4.0.0. If we introduce a new minor API version (4.1), well then that would be a minor change, and the TO version would be updated to 4.1.0. After that, if we only introduced bug fixes or other improvements that didn't affect the API, we would update the TO version to 4.1.1. Having our component versions match the ATC release version is just a convention that we've chosen to follow as a project, but we can definitely change that. In fact, if we gave components their own version, that would allow us to more easily release components by themselves and get them into production faster, rather than waiting for the ATC release in order to upgrade everything or building from master periodically. We've been kicking around the idea of breaking out components into their own repos, and I think we'd probably need to give them their own versions and releases at that point anyways. - Rawlin On Tue, Jul 20, 2021 at 1:44 PM Jeremy Mitchell <mitchell...@gmail.com> wrote: > > All good points but also consider this, ATC is version 5.x, for example, so > all the components are version 5.x, right? meaning the TO component (aka > the TO api) is.... version 5.x.... :) > > so really TO (api) seems to have many versions (5.x inherited from the > project and 2.x, 3.x, 4.x, the versions of the "interface"). yes, > confusing... > > > > On Tue, Jul 20, 2021 at 1:32 PM Robert O Butts <r...@apache.org> wrote: > > > > Also, after years of API confusion, is it time to simply sync the ATC > > > version with the API version (brennan has touched on this in the past) > > > starting with our "next" API version. So instead of APIv5, we'd just jump > > > to APIv7. ex: > > > > I strongly disagree with "synchronizing" the API and project version. The > > idea that they need to be the same is deeply confused about what they are, > > and making them the same will reinforce that confusion with the people who > > are confused. > > > > The project version and the API version are completely independent and > > unrelated things. The idea that they need to be versioned together and are > > somehow the same thing is incredibly confused and mistaken about the > > fundamental idea of what an API is and what a code project is. > > > > The API is the API. The project is the project. An API is an Application > > Programming Interface: an interface, like an electric outlet or a water > > faucet connection. The Traffic Control project is a code project: a > > collection of applications, written in code, to do a thing, in this case a > > CDN. > > > > These are completely, entirely, totally different things. It would be like > > working for a company that sells both laptops and capacitors, and saying, > > "Our capacitors and laptops should have the same serial numbers, because > > they both contain iron atoms." > > > > Yes, the code in the project serves certain APIs. But the two things are > > completely independent. Giving them the same version will reinforce the > > wrong and confused belief that they're somehow the same thing, when > > literally the only thing they have in common as ideas is that they're two > > version numbers published by Apache Traffic Control. > > > > Moreover, All Traffic Control applications will always have to serve at > > least one major version back, in order to make it possible to upgrade. So > > the confused idea that they're somehow the same will be made even more > > confusing, because now people think "The API is the same as the Project, > > and the version proves it, but the project has to serve multiple APIs." > > Making people even more confused. > > > > In fact, I'm inclined to think making the versions completely different > > schemes, such as one being letters and the other numbers, would help reduce > > the confusion, and make it more clear that the two versioned things are > > completely unrelated. > > > > > > On Tue, Jul 20, 2021 at 1:00 PM Jeremy Mitchell <mitchell...@gmail.com> > > wrote: > > > > > ^^ I'm good with this. > > > > > > Also, after years of API confusion, is it time to simply sync the ATC > > > version with the API version (brennan has touched on this in the past) > > > starting with our "next" API version. So instead of APIv5, we'd just jump > > > to APIv7. ex: > > > > > > ATCv7 supports APIv7 (to get inline with ATC version) and APIv4 (the api > > > version from ATCv6) > > > ATCv8 supports APIv8 and APIv7 > > > etc > > > > > > but then i guess that begs the question, if we bump the major ATC version > > > for another reason (big feature or something), does that mean we have to > > > bump the API version if not really necessary just to keep ATCv == APIv? > > > > > > jeremy > > > > > > On Mon, Jul 19, 2021 at 1:08 PM Rawlin Peters <raw...@apache.org> wrote: > > > > > > > > What kind of backward compatibility expectation are we aiming for > > here? > > > > With 1.x we were coming from 5+ years of backward compatibility > > > > > > > > I don't think we ever intended for API 1.x to live for so long, but we > > > > also never promised an agreed-upon amount of time for backwards > > > > compatibility. I think the intention is that we'd like to have one > > > > major release cycle where both major API versions are supported (in > > > > order for clients to have a transitionary period), then we are free to > > > > remove the deprecated API version in the following release. The amount > > > > of time we remain backwards-compatible should really depend on how > > > > long the release cycles are, which we're aiming for quarterly. > > > > > > > > I agree it is a lot of headache to update 3rd party tooling as API > > > > versions are deprecated and removed (which is why I'm hoping we don't > > > > introduce another major API version very soon), but hopefully the vast > > > > majority of cases are simply updating the URLs from 2.0 or 3.0 to 4.0, > > > > since there should only be a small number of breakages from 2.0 to 4.0 > > > > (mostly servers-related routes) that would actually require changing > > > > more than just the URL. Migrating from 1.x has probably been more > > > > difficult since we dropped a lot of redundant routes. > > > > > > > > - Rawlin > > > > > > > > > > > > - Rawlin > > > > > > > > On Mon, Jul 19, 2021 at 11:43 AM Gray, Jonathan > > > > <jonathan_g...@comcast.com.invalid> wrote: > > > > > > > > > > What kind of backward compatibility expectation are we aiming for > > here? > > > > With 1.x we were coming from 5+ years of backward compatibility and now > > > it > > > > seems like we’re aiming for < 1 year with rotation at every major rev. > > > > That’s a lot of headache for 3rd party tooling support to constantly be > > > > changing regardless if that means you’re upgrading SDK dependencies or > > > raw > > > > HTTP calls. > > > > > > > > > > Jonathan G > > > > > > > > > > From: Rawlin Peters <raw...@apache.org> > > > > > Date: Friday, July 16, 2021 at 11:54 AM > > > > > To: dev@trafficcontrol.apache.org <dev@trafficcontrol.apache.org> > > > > > Subject: [EXTERNAL] Re: Deprecate APIv2 and v3 > > > > > +1 on deprecating API v2-3 with the release of ACTv6 and removing > > them > > > > > in ATCv7. Hopefully we won't need a TO API v5 very soon so we can > > have > > > > > a break from the API instability. > > > > > > > > > > +1 on not requiring every v2 and v3 endpoint to return deprecation > > > > > notices. I think just mentioning it on the mailing list, the > > > > > changelog, and the docs should cover it. Updating all the v2/v3 > > > > > endpoints to return deprecation notices would be quite a lot of code > > > > > change with very little benefit IMO. However, for certain endpoints > > > > > that have no v4 equivalent, we are returning deprecation notices > > (e.g. > > > > > cachegroup parameters). > > > > > > > > > > - Rawlin > > > > > > > > > > On Fri, Jul 16, 2021 at 11:28 AM ocket 8888 <ocket8...@gmail.com> > > > wrote: > > > > > > > > > > > > With the release of APIv4 in ATCv6, should we simultaneously > > > deprecate > > > > > > APIv2 and APIv3? I think so, that'll mean we can remove them in > > > ATCv7, > > > > > > whereupon the stable API 4.0 will have existed for a full major > > rev, > > > > and > > > > > > APIv5 will ostensibly be released (if not sooner, since we could do > > > > that > > > > > > e.g. in a 6.1). > > > > > > > > > > > > If so, we should also discuss what that will mean materially. With > > > > > > endpoints that disappear between API versions we have them return > > > > > > warning-level alerts that indicate they won't be available on > > > upgrade, > > > > but > > > > > > for APIv1 as a whole we didn't issue any kind of formal notice > > afaik, > > > > not > > > > > > even a changelog entry. I think the right answer is somewhere > > between > > > > these > > > > > > - a changelog entry and notices on the APIv2 and APIv3 reference > > > > sections > > > > > > of the documentation. I don't think it's necessary to mention on > > each > > > > > > endpoint that the entire API version is deprecated, either in the > > > > > > documentation or in the API through Alerts. > > > > > > > > >
