Be aware that the ansible deployment code is dependent on v2 for the moment until it’s updated again. Deprecation is fine, but if it’s removed we’ll be in the same boat we were in when 1.x got removed.
Jonathan G From: ocket 8888 <ocket8...@gmail.com> Date: Tuesday, August 3, 2021 at 10:53 AM To: dev@trafficcontrol.apache.org <dev@trafficcontrol.apache.org> Subject: Re: [EXTERNAL] Re: Deprecate APIv2 and v3 Alright, it seems like nobody is opposed to deprecating APIv2 (please correct me if that's wrong), so assuming that's the case to be perfectly clear on what everyone wants to do, I'd like to call for a final vote on whether or not to deprecate APIv3, so that if we do we can get it into the docs and changelog by the 16th when the release is currently set to be cut. I'm +1 on my own proposal, unsurprisingly. On Wed, Jul 28, 2021 at 11:28 AM ocket 8888 <ocket8...@gmail.com> wrote: > I don't disagree with any of that. > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan > <jonathan_g...@comcast.com.invalid> wrote: > >> > so that APIv3 doesn't become the next entrenched version to be >> hard-coded into a plethora of obscure scripts so that it takes over a year >> to switch. >> >> Those scripts are just as important as the ATC project itself when it >> comes to production operations. API version churn is expensive and it’s a >> symbiotic relationship. OSS projects that maintain backward compatibility >> are easier to work with and attain greater adoption. It’s just another >> facet of encouraging adoption just like good PR processes and tests. >> >> Jonathan G >> >> From: ocket 8888 <ocket8...@gmail.com> >> Date: Tuesday, July 27, 2021 at 5:55 PM >> To: dev@trafficcontrol.apache.org <dev@trafficcontrol.apache.org> >> Subject: Re: [EXTERNAL] Re: Deprecate APIv2 and v3 >> I have a link to the mailing list discussion: >> >> https://urldefense.com/v3/__https://lists.apache.org/thread.html/b857afc7b52e72b2e60ebb3eb594b6fa5dd0ed3c9af5a17b58ee4a99*40*3Cdev.trafficcontrol.apache.org*3E__;JSUl!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fPda49a$<https://urldefense.com/v3/__https:/lists.apache.org/thread.html/b857afc7b52e72b2e60ebb3eb594b6fa5dd0ed3c9af5a17b58ee4a99*40*3Cdev.trafficcontrol.apache.org*3E__;JSUl!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fPda49a$> >> < >> https://urldefense.com/v3/__https:/lists.apache.org/thread.html/b857afc7b52e72b2e60ebb3eb594b6fa5dd0ed3c9af5a17b58ee4a99*40*3Cdev.trafficcontrol.apache.org*3E__;JSUl!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fPda49a$ >> > >> >> People can still use APIv3 (and v2) until ATCv7. if we don't deprecate >> APIv3, then we're going to be in the same boat next time around when APIv5 >> happens - which I know some people aren't thrilled about but I think we're >> going to need it almost immediately after ATCv6 drops - where we have two >> supported legacy API versions carrying around cruft and tech debt. IMO, we >> need to rip this band-aid off sooner rather than later, so that APIv3 >> doesn't become the next entrenched version to be hard-coded into a >> plethora >> of obscure scripts so that it takes over a year to switch. >> >> >> >> On Tue, Jul 27, 2021 at 4:05 PM Dave Neuman <neu...@apache.org> wrote: >> >> > 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://urldefense.com/v3/__https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html*api-v4-routes__;Iw!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fyRz_Si$<https://urldefense.com/v3/__https:/traffic-control-cdn.readthedocs.io/en/latest/api/index.html*api-v4-routes__;Iw!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fyRz_Si$> >> < >> https://urldefense.com/v3/__https:/traffic-control-cdn.readthedocs.io/en/latest/api/index.html*api-v4-routes__;Iw!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fyRz_Si$ >> > >> > > >> > >> > > >> > Those are the docs for the master branch. >> > > >> > There is no mention of API 4.x in the ATC 5.1.2 docs: >> > > >> > >> https://urldefense.com/v3/__https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html__;!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9Wv2iauE$<https://urldefense.com/v3/__https:/traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html__;!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9Wv2iauE$> >> < >> https://urldefense.com/v3/__https:/traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html__;!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9Wv2iauE$ >> > >> > > >> > >> > > >> > -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://urldefense.com/v3/__https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html*api-v4-routes__;Iw!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fyRz_Si$<https://urldefense.com/v3/__https:/traffic-control-cdn.readthedocs.io/en/latest/api/index.html*api-v4-routes__;Iw!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fyRz_Si$> >> < >> https://urldefense.com/v3/__https:/traffic-control-cdn.readthedocs.io/en/latest/api/index.html*api-v4-routes__;Iw!!CQl3mcHX2A!Q_lvH7GunLsRSIigt4CHJwosp0fih_-ArK7UVI4Z2cr5_J00BL2ZxgbYrYcu9fyRz_Si$ >> > >> > > >> > > >> > > >> > > 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. >> > > >> > > > > > > > > > > >> > > >> > > > > > > > > > >> > > >> > > > > > > > > >> > > >> > > > > > > > >> > > >> > > > > > > >> > > >> > > > > > >> > > >> > > > > >> > > >> > > > >> > > >> > > >> > > >> >> > > > >> > > >> > >> >
