I think we can probably just do one for both, assuming the vote for v3 sees no "-1"s.
On Tue, Aug 3, 2021 at 12:08 PM Jeremy Mitchell <mitchell...@gmail.com> wrote: > +1 for deprecation notices added to 2.x and 3.x in TC 6.x. <-- 2 github > issues for that? > > On Tue, Aug 3, 2021 at 11:17 AM Rawlin Peters <raw...@apache.org> wrote: > > > +1 > > > > - Rawlin > > > > On Tue, Aug 3, 2021 at 11:01 AM Zach Hoffman <zrhoff...@apache.org> > wrote: > > > > > > > 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. > > > > > > +1 > > > > > > On Tue, Aug 3, 2021 at 10:59 AM ocket 8888 <ocket8...@gmail.com> > wrote: > > > > > > > Removal is definitely not on the table until at least ATCv7 > > > > > > > > On Tue, Aug 3, 2021 at 10:56 AM Gray, Jonathan > > > > <jonathan_g...@comcast.com.invalid> wrote: > > > > > > > > > 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. > > > > > >> > > >> > > > > > > > > > > > > > > > >> > > >> > > > > > > > > > > > > > > >> > > >> > > > > > > > > > > > > > >> > > >> > > > > > > > > > > > > >> > > >> > > > > > > > > > > > >> > > >> > > > > > > > > > > >> > > >> > > > > > > > > > >> > > >> > > > > > > > > >> > > >> > > > > > > > >> > > >> > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > > > > > > > > > > > > > >
