The reason that's relevant being that deprecating 2.0 and 3.0 with the release of 4.0 is in-line with that strategy.
On Tue, Jul 27, 2021 at 2:23 PM ocket 8888 <ocket8...@gmail.com> wrote: > I know it doesn't change the reality of our situation, but fwiw APIv1 > should've already been gone. From our discussion regarding versioning when > we were making APIv2 prior to ATC release 4.0: > > > TC 4.0: > > - API 1.x supported, some deprecation notices > > > > TC 4.1: > > - API 1.x still supported, deprecation notices added to endpoints not > graduated to 2.0 > > - API 2.0 supported, consisting of 1.x endpoints that were graduated > > - starting with this release, you need to start migrating external > clients off of 1.x over to 2.0 > > > > TC 4.2: > > - internal clients (e.g. TM, TR, etc) will be migrated off API 1.x over > to 2.0. Doing this step after 4.1 adds confidence that 1.x is still > supported alongside 2.0 in order to provide a smooth migration period for > API clients. > > > > TC 5.0: > > - API 1.x no longer supported, only API 2.x is supported > > The only reason APIv1 exists in 5.x is because "starting with this > release, you need to start migrating external clients off of 1.x over to > 2.0" wound up taking much, much longer than we thought it would. The plan, > as I understand it, was always for only three API versions to ever coexist > - and only two released versions: > - legacy version, deprecated, what everyone's using prior to upgrade to > ATC version that deprecates it > - supported version, latest released > - development version, not released, nobody should use except ATC > components under active development. > > On Tue, Jul 27, 2021 at 11:56 AM Rawlin Peters <raw...@apache.org> wrote: > >> I guess the question now is what do we think is "fair" for our users? >> Shouldn't they decide? Can we survey them? If it were me doing the >> updates, I think I'd prefer to do the 2nd update as close to the 1st >> update as possible, since those necessary changes would still be fresh >> in memory. Especially knowing that a 2nd update is coming at some >> point, I'd rather just get it over with as soon as possible and not >> have to worry about planning for it later down the line. >> >> - Rawlin >> >> On Tue, Jul 27, 2021 at 11:36 AM Zach Hoffman <zrhoff...@apache.org> >> wrote: >> > >> > > > Does API 4.x exist before 6.0? >> > > According to the most recent docs, yes. >> > >> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes >> > >> > Those are the docs for the master branch. >> > There is no mention of API 4.x in the ATC 5.1.2 docs: >> > https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html >> > >> > -Zach >> > >> > >> > On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan >> > <jonathan_g...@comcast.com.invalid> wrote: >> > >> > > According to the most recent docs, yes. >> > > >> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes >> > > >> > > Jonathan G >> > > >> > > From: Dave Neuman <neu...@apache.org> >> > > Date: Tuesday, July 27, 2021 at 10:59 AM >> > > To: dev@trafficcontrol.apache.org <dev@trafficcontrol.apache.org> >> > > Subject: Re: [EXTERNAL] Re: Deprecate APIv2 and v3 >> > > Does API 4.x exist before 6.0? >> > > I am worried about basically telling our users that before they can >> go to >> > > 6.x they have to get off API 1.x but the latest at that point is 3.x >> so >> > > then we are turning around and saying they have to update again. I >> would >> > > prefer if we gave more time and did 2.0 now and 3.0 in our next >> release. >> > > I am not going to -1 because ultimately it is not going to impact me >> as >> > > much as those that have already shared opinions, but I did want to >> make >> > > sure we aren't being unfair to our users. >> > > >> > > Thanks, >> > > Dave >> > > >> > > On Mon, Jul 26, 2021 at 4:40 PM Zach Hoffman <zrhoff...@apache.org> >> wrote: >> > > >> > > > +1 for deprecating APIv2 and APIv3. >> > > > >> > > > -Zach >> > > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell < >> mitchell...@gmail.com> >> > > > wrote: >> > > > >> > > > > sorry about that. i'm +1 on deprecating APIv2 and APIv3 in the >> fashion >> > > > you >> > > > > mentioned. >> > > > > >> > > > > On Tue, Jul 20, 2021 at 2:39 PM ocket 8888 <ocket8...@gmail.com> >> > > wrote: >> > > > > >> > > > > > I don't really want to propose anything more complex than >> deprecating >> > > > > APIv2 >> > > > > > and APIv3 in this thread. Which isn't to say that I don't have >> > > > opinions >> > > > > on >> > > > > > all of this, but it's starting to confuse the point when people >> are >> > > > > giving >> > > > > > +1s and -1s on things besides the thread subject. >> > > > > > >> > > > > > On Tue, Jul 20, 2021 at 2:17 PM Robert O Butts <r...@apache.org> >> > > wrote: >> > > > > > >> > > > > > > > so really TO (api) seems to have many versions >> > > > > > > >> > > > > > > The Traffic Ops application has a single project/app version. >> The >> > > TO >> > > > > > > Application "serves" multiple API Versions, which are >> unrelated to >> > > > that >> > > > > > > application version. TO doesn't "have" many versions, it has >> one >> > > > > > version. A >> > > > > > > particular Traffic Ops version "10" might serve API versions >> X,Y,Z. >> > > > But >> > > > > > > those API versions aren't "part" of the Traffic Ops Versions. >> There >> > > > > > exists >> > > > > > > no "Traffic Ops version 10" which serves any other API >> versions. >> > > And >> > > > > > there >> > > > > > > might exist other Traffic Ops versions which also serve >> X,Y,Z. So, >> > > TO >> > > > > > only >> > > > > > > has one version, "10." X,Y,Z are unrelated to 10, except that >> 10 is >> > > > > > > documented as serving X,Y,Z. >> > > > > > > >> > > > > > > > ATC is version 5.x, for example, so all the components are >> > > version >> > > > > 5.x, >> > > > > > > right? >> > > > > > > >> > > > > > > As an aside, IMO having separate application versions would >> make a >> > > > lot >> > > > > of >> > > > > > > sense and make a lot of things easier. I don't want to push >> for >> > > that >> > > > > > right >> > > > > > > now, but something to think about. Maybe part of the version >> after >> > > > the >> > > > > > > project, e.g. ATC could be Version 10.11 and Traffic Ops >> could have >> > > > its >> > > > > > own >> > > > > > > application version 5.7, so Traffic Ops would have the >> complete >> > > > version >> > > > > > > "atc-10.11-to-5.7-hash-abc123.rpm" or whatever. I think that >> might >> > > > make >> > > > > > it >> > > > > > > clearer when one app hasn't changed even if the project did, >> > > > especially >> > > > > > > with our apps that don't change very often. Something to think >> > > about. >> > > > > > > >> > > > > > > >> > > > > > > >> > > > > > > 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. >> > > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > >> >
