Isn't this email almost like a survey? Anyone doing API work is probably on this ML or should be.
Brennan, do you have a link to that discussion? If it wasn't on list then it didn't happen ;) Like I said, I am not going to -1 the proposal but given that I now know that 4.x isn't introduced until ATC 6.x, I don't see the big hurry to remove 2.x and 3.x. It seems a little premature to me, maybe we just do 2.x and not 3.x? Presumably folks that updated from 1.x went to 3.x and we should give them a chance to use that before ripping it out too. Also, as an aside, it seems like we are adding more and more to 6.x, if we want to get that out we should probably just focus on what needs to be completed and not adding more to it. --Dave On Tue, Jul 27, 2021 at 2:24 PM ocket 8888 <ocket8...@gmail.com> wrote: > 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. > >> > > > > > > > > > > > >> > > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > >
