You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficcontrol.apache.org by ocket 8888 <oc...@gmail.com> on 2021/08/03 16:53:06 UTC
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 <oc...@gmail.com> wrote:
> I don't disagree with any of that.
>
> On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> <Jo...@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 <oc...@gmail.com>
>> Date: Tuesday, July 27, 2021 at 5:55 PM
>> To: dev@trafficcontrol.apache.org <de...@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$
>> >
>>
>> 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 <ne...@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 <oc...@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 <oc...@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 <ra...@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 <
>> zrhoffman@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$
>> >
>> > > >> >
>> > > >> > 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$
>> >
>> > > >> >
>> > > >> > -Zach
>> > > >> >
>> > > >> >
>> > > >> > On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
>> > > >> > <Jo...@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$
>> >
>> > > >> > >
>> > > >> > > Jonathan G
>> > > >> > >
>> > > >> > > From: Dave Neuman <ne...@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 <
>> > zrhoffman@apache.org>
>> > > >> wrote:
>> > > >> > >
>> > > >> > > > +1 for deprecating APIv2 and APIv3.
>> > > >> > > >
>> > > >> > > > -Zach
>> > > >> > > >
>> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
>> > > >> mitchell852@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 <
>> > ocket8888@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 <
>> > > rob@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 <
>> > > >> > > > mitchell852@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 <
>> > > >> rob@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 <
>> > > >> > > > > > mitchell852@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 <
>> > > >> > > > rawlin@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
>> > > >> > > > > > > > > > > <Jo...@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 <ra...@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 <
>> > > >> > > > > > ocket8888@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.
>> > > >> > > > > > > > > > >
>> > > >> > > > > > > > > >
>> > > >> > > > > > > > >
>> > > >> > > > > > > >
>> > > >> > > > > > >
>> > > >> > > > > >
>> > > >> > > > >
>> > > >> > > >
>> > > >> > >
>> > > >>
>> > > >
>> > >
>> >
>>
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by ocket 8888 <oc...@gmail.com>.
Alright, looks like none stand opposed, so I've opened an issue to track
this: https://github.com/apache/trafficcontrol/issues/6082
Thanks for your time, everyone!
On Tue, Aug 3, 2021 at 1:54 PM Taylor Frey <ta...@gmail.com> wrote:
> I, too, +1 deprecation notices for both 2.x and 3.x for Traffic Ops API in
> ATC 6.+
>
> On Tue, Aug 3, 2021 at 1:18 PM ocket 8888 <oc...@gmail.com> wrote:
>
> > 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 <mi...@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 <ra...@apache.org>
> wrote:
> > >
> > > > +1
> > > >
> > > > - Rawlin
> > > >
> > > > On Tue, Aug 3, 2021 at 11:01 AM Zach Hoffman <zr...@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 <oc...@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
> > > > > > <Jo...@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 <oc...@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 <
> ocket8888@gmail.com
> > >
> > > > wrote:
> > > > > > >
> > > > > > > > I don't disagree with any of that.
> > > > > > > >
> > > > > > > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > > > > > > > <Jo...@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 <oc...@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 <
> > neuman@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 <
> > > ocket8888@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 <
> > > > ocket8888@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 <
> > > > > > rawlin@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 <
> > > > > > > >> zrhoffman@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
> > > > > > > >> > > >> > <Jo...@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 <ne...@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 <
> > > > > > > >> > zrhoffman@apache.org>
> > > > > > > >> > > >> wrote:
> > > > > > > >> > > >> > >
> > > > > > > >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> > > > > > > >> > > >> > > >
> > > > > > > >> > > >> > > > -Zach
> > > > > > > >> > > >> > > >
> > > > > > > >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy
> Mitchell <
> > > > > > > >> > > >> mitchell852@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 <
> > > > > > > >> > ocket8888@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
> > > <
> > > > > > > >> > > rob@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 <
> > > > > > > >> > > >> > > > mitchell852@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 <
> > > > > > > >> > > >> rob@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 <
> > > > > > > >> > > >> > > > > > mitchell852@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 <
> > > > > > > >> > > >> > > > rawlin@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_Gray@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 <
> > > > rawlin@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 <
> > > > > > > >> > > >> > > > > > ocket8888@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.
> > > > > > > >> > > >> > > > > > > > > > >
> > > > > > > >> > > >> > > > > > > > > >
> > > > > > > >> > > >> > > > > > > > >
> > > > > > > >> > > >> > > > > > > >
> > > > > > > >> > > >> > > > > > >
> > > > > > > >> > > >> > > > > >
> > > > > > > >> > > >> > > > >
> > > > > > > >> > > >> > > >
> > > > > > > >> > > >> > >
> > > > > > > >> > > >>
> > > > > > > >> > > >
> > > > > > > >> > >
> > > > > > > >> >
> > > > > > > >>
> > > > > > > >
> > > > > > >
> > > > > >
> > > >
> > >
> >
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by Taylor Frey <ta...@gmail.com>.
I, too, +1 deprecation notices for both 2.x and 3.x for Traffic Ops API in
ATC 6.+
On Tue, Aug 3, 2021 at 1:18 PM ocket 8888 <oc...@gmail.com> wrote:
> 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 <mi...@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 <ra...@apache.org> wrote:
> >
> > > +1
> > >
> > > - Rawlin
> > >
> > > On Tue, Aug 3, 2021 at 11:01 AM Zach Hoffman <zr...@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 <oc...@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
> > > > > <Jo...@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 <oc...@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 <ocket8888@gmail.com
> >
> > > wrote:
> > > > > >
> > > > > > > I don't disagree with any of that.
> > > > > > >
> > > > > > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > > > > > > <Jo...@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 <oc...@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 <
> neuman@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 <
> > ocket8888@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 <
> > > ocket8888@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 <
> > > > > rawlin@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 <
> > > > > > >> zrhoffman@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
> > > > > > >> > > >> > <Jo...@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 <ne...@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 <
> > > > > > >> > zrhoffman@apache.org>
> > > > > > >> > > >> wrote:
> > > > > > >> > > >> > >
> > > > > > >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> > > > > > >> > > >> > > >
> > > > > > >> > > >> > > > -Zach
> > > > > > >> > > >> > > >
> > > > > > >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
> > > > > > >> > > >> mitchell852@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 <
> > > > > > >> > ocket8888@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
> > <
> > > > > > >> > > rob@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 <
> > > > > > >> > > >> > > > mitchell852@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 <
> > > > > > >> > > >> rob@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 <
> > > > > > >> > > >> > > > > > mitchell852@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 <
> > > > > > >> > > >> > > > rawlin@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_Gray@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 <
> > > rawlin@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 <
> > > > > > >> > > >> > > > > > ocket8888@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.
> > > > > > >> > > >> > > > > > > > > > >
> > > > > > >> > > >> > > > > > > > > >
> > > > > > >> > > >> > > > > > > > >
> > > > > > >> > > >> > > > > > > >
> > > > > > >> > > >> > > > > > >
> > > > > > >> > > >> > > > > >
> > > > > > >> > > >> > > > >
> > > > > > >> > > >> > > >
> > > > > > >> > > >> > >
> > > > > > >> > > >>
> > > > > > >> > > >
> > > > > > >> > >
> > > > > > >> >
> > > > > > >>
> > > > > > >
> > > > > >
> > > > >
> > >
> >
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by ocket 8888 <oc...@gmail.com>.
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 <mi...@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 <ra...@apache.org> wrote:
>
> > +1
> >
> > - Rawlin
> >
> > On Tue, Aug 3, 2021 at 11:01 AM Zach Hoffman <zr...@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 <oc...@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
> > > > <Jo...@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 <oc...@gmail.com>
> > > > > Date: Tuesday, August 3, 2021 at 10:53 AM
> > > > > To: dev@trafficcontrol.apache.org <de...@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 <oc...@gmail.com>
> > wrote:
> > > > >
> > > > > > I don't disagree with any of that.
> > > > > >
> > > > > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > > > > > <Jo...@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 <oc...@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 <ne...@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 <
> ocket8888@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 <
> > ocket8888@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 <
> > > > rawlin@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 <
> > > > > >> zrhoffman@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
> > > > > >> > > >> > <Jo...@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 <ne...@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 <
> > > > > >> > zrhoffman@apache.org>
> > > > > >> > > >> wrote:
> > > > > >> > > >> > >
> > > > > >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> > > > > >> > > >> > > >
> > > > > >> > > >> > > > -Zach
> > > > > >> > > >> > > >
> > > > > >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
> > > > > >> > > >> mitchell852@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 <
> > > > > >> > ocket8888@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
> <
> > > > > >> > > rob@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 <
> > > > > >> > > >> > > > mitchell852@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 <
> > > > > >> > > >> rob@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 <
> > > > > >> > > >> > > > > > mitchell852@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 <
> > > > > >> > > >> > > > rawlin@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
> > > > > >> > > >> > > > > > > > > > > <Jo...@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 <
> > rawlin@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 <
> > > > > >> > > >> > > > > > ocket8888@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.
> > > > > >> > > >> > > > > > > > > > >
> > > > > >> > > >> > > > > > > > > >
> > > > > >> > > >> > > > > > > > >
> > > > > >> > > >> > > > > > > >
> > > > > >> > > >> > > > > > >
> > > > > >> > > >> > > > > >
> > > > > >> > > >> > > > >
> > > > > >> > > >> > > >
> > > > > >> > > >> > >
> > > > > >> > > >>
> > > > > >> > > >
> > > > > >> > >
> > > > > >> >
> > > > > >>
> > > > > >
> > > > >
> > > >
> >
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by Jeremy Mitchell <mi...@gmail.com>.
+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 <ra...@apache.org> wrote:
> +1
>
> - Rawlin
>
> On Tue, Aug 3, 2021 at 11:01 AM Zach Hoffman <zr...@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 <oc...@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
> > > <Jo...@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 <oc...@gmail.com>
> > > > Date: Tuesday, August 3, 2021 at 10:53 AM
> > > > To: dev@trafficcontrol.apache.org <de...@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 <oc...@gmail.com>
> wrote:
> > > >
> > > > > I don't disagree with any of that.
> > > > >
> > > > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > > > > <Jo...@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 <oc...@gmail.com>
> > > > >> Date: Tuesday, July 27, 2021 at 5:55 PM
> > > > >> To: dev@trafficcontrol.apache.org <de...@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 <ne...@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 <ocket8888@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 <
> ocket8888@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 <
> > > rawlin@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 <
> > > > >> zrhoffman@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
> > > > >> > > >> > <Jo...@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 <ne...@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 <
> > > > >> > zrhoffman@apache.org>
> > > > >> > > >> wrote:
> > > > >> > > >> > >
> > > > >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> > > > >> > > >> > > >
> > > > >> > > >> > > > -Zach
> > > > >> > > >> > > >
> > > > >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
> > > > >> > > >> mitchell852@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 <
> > > > >> > ocket8888@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 <
> > > > >> > > rob@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 <
> > > > >> > > >> > > > mitchell852@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 <
> > > > >> > > >> rob@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 <
> > > > >> > > >> > > > > > mitchell852@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 <
> > > > >> > > >> > > > rawlin@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
> > > > >> > > >> > > > > > > > > > > <Jo...@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 <
> rawlin@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 <
> > > > >> > > >> > > > > > ocket8888@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.
> > > > >> > > >> > > > > > > > > > >
> > > > >> > > >> > > > > > > > > >
> > > > >> > > >> > > > > > > > >
> > > > >> > > >> > > > > > > >
> > > > >> > > >> > > > > > >
> > > > >> > > >> > > > > >
> > > > >> > > >> > > > >
> > > > >> > > >> > > >
> > > > >> > > >> > >
> > > > >> > > >>
> > > > >> > > >
> > > > >> > >
> > > > >> >
> > > > >>
> > > > >
> > > >
> > >
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by Rawlin Peters <ra...@apache.org>.
+1
- Rawlin
On Tue, Aug 3, 2021 at 11:01 AM Zach Hoffman <zr...@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 <oc...@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
> > <Jo...@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 <oc...@gmail.com>
> > > Date: Tuesday, August 3, 2021 at 10:53 AM
> > > To: dev@trafficcontrol.apache.org <de...@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 <oc...@gmail.com> wrote:
> > >
> > > > I don't disagree with any of that.
> > > >
> > > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > > > <Jo...@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 <oc...@gmail.com>
> > > >> Date: Tuesday, July 27, 2021 at 5:55 PM
> > > >> To: dev@trafficcontrol.apache.org <de...@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 <ne...@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 <oc...@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 <oc...@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 <
> > rawlin@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 <
> > > >> zrhoffman@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
> > > >> > > >> > <Jo...@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 <ne...@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 <
> > > >> > zrhoffman@apache.org>
> > > >> > > >> wrote:
> > > >> > > >> > >
> > > >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> > > >> > > >> > > >
> > > >> > > >> > > > -Zach
> > > >> > > >> > > >
> > > >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
> > > >> > > >> mitchell852@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 <
> > > >> > ocket8888@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 <
> > > >> > > rob@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 <
> > > >> > > >> > > > mitchell852@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 <
> > > >> > > >> rob@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 <
> > > >> > > >> > > > > > mitchell852@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 <
> > > >> > > >> > > > rawlin@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
> > > >> > > >> > > > > > > > > > > <Jo...@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 <ra...@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 <
> > > >> > > >> > > > > > ocket8888@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.
> > > >> > > >> > > > > > > > > > >
> > > >> > > >> > > > > > > > > >
> > > >> > > >> > > > > > > > >
> > > >> > > >> > > > > > > >
> > > >> > > >> > > > > > >
> > > >> > > >> > > > > >
> > > >> > > >> > > > >
> > > >> > > >> > > >
> > > >> > > >> > >
> > > >> > > >>
> > > >> > > >
> > > >> > >
> > > >> >
> > > >>
> > > >
> > >
> >
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by Zach Hoffman <zr...@apache.org>.
> 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 <oc...@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
> <Jo...@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 <oc...@gmail.com>
> > Date: Tuesday, August 3, 2021 at 10:53 AM
> > To: dev@trafficcontrol.apache.org <de...@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 <oc...@gmail.com> wrote:
> >
> > > I don't disagree with any of that.
> > >
> > > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > > <Jo...@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 <oc...@gmail.com>
> > >> Date: Tuesday, July 27, 2021 at 5:55 PM
> > >> To: dev@trafficcontrol.apache.org <de...@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 <ne...@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 <oc...@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 <oc...@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 <
> rawlin@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 <
> > >> zrhoffman@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
> > >> > > >> > <Jo...@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 <ne...@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 <
> > >> > zrhoffman@apache.org>
> > >> > > >> wrote:
> > >> > > >> > >
> > >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> > >> > > >> > > >
> > >> > > >> > > > -Zach
> > >> > > >> > > >
> > >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
> > >> > > >> mitchell852@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 <
> > >> > ocket8888@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 <
> > >> > > rob@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 <
> > >> > > >> > > > mitchell852@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 <
> > >> > > >> rob@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 <
> > >> > > >> > > > > > mitchell852@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 <
> > >> > > >> > > > rawlin@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
> > >> > > >> > > > > > > > > > > <Jo...@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 <ra...@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 <
> > >> > > >> > > > > > ocket8888@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.
> > >> > > >> > > > > > > > > > >
> > >> > > >> > > > > > > > > >
> > >> > > >> > > > > > > > >
> > >> > > >> > > > > > > >
> > >> > > >> > > > > > >
> > >> > > >> > > > > >
> > >> > > >> > > > >
> > >> > > >> > > >
> > >> > > >> > >
> > >> > > >>
> > >> > > >
> > >> > >
> > >> >
> > >>
> > >
> >
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by ocket 8888 <oc...@gmail.com>.
Removal is definitely not on the table until at least ATCv7
On Tue, Aug 3, 2021 at 10:56 AM Gray, Jonathan
<Jo...@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 <oc...@gmail.com>
> Date: Tuesday, August 3, 2021 at 10:53 AM
> To: dev@trafficcontrol.apache.org <de...@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 <oc...@gmail.com> wrote:
>
> > I don't disagree with any of that.
> >
> > On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> > <Jo...@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 <oc...@gmail.com>
> >> Date: Tuesday, July 27, 2021 at 5:55 PM
> >> To: dev@trafficcontrol.apache.org <de...@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 <ne...@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 <oc...@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 <oc...@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 <rawlin@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 <
> >> zrhoffman@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
> >> > > >> > <Jo...@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 <ne...@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 <
> >> > zrhoffman@apache.org>
> >> > > >> wrote:
> >> > > >> > >
> >> > > >> > > > +1 for deprecating APIv2 and APIv3.
> >> > > >> > > >
> >> > > >> > > > -Zach
> >> > > >> > > >
> >> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
> >> > > >> mitchell852@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 <
> >> > ocket8888@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 <
> >> > > rob@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 <
> >> > > >> > > > mitchell852@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 <
> >> > > >> rob@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 <
> >> > > >> > > > > > mitchell852@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 <
> >> > > >> > > > rawlin@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
> >> > > >> > > > > > > > > > > <Jo...@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 <ra...@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 <
> >> > > >> > > > > > ocket8888@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.
> >> > > >> > > > > > > > > > >
> >> > > >> > > > > > > > > >
> >> > > >> > > > > > > > >
> >> > > >> > > > > > > >
> >> > > >> > > > > > >
> >> > > >> > > > > >
> >> > > >> > > > >
> >> > > >> > > >
> >> > > >> > >
> >> > > >>
> >> > > >
> >> > >
> >> >
> >>
> >
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by "Gray, Jonathan" <Jo...@comcast.com.INVALID>.
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 <oc...@gmail.com>
Date: Tuesday, August 3, 2021 at 10:53 AM
To: dev@trafficcontrol.apache.org <de...@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 <oc...@gmail.com> wrote:
> I don't disagree with any of that.
>
> On Wed, Jul 28, 2021 at 9:01 AM Gray, Jonathan
> <Jo...@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 <oc...@gmail.com>
>> Date: Tuesday, July 27, 2021 at 5:55 PM
>> To: dev@trafficcontrol.apache.org <de...@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 <ne...@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 <oc...@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 <oc...@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 <ra...@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 <
>> zrhoffman@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
>> > > >> > <Jo...@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 <ne...@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 <
>> > zrhoffman@apache.org>
>> > > >> wrote:
>> > > >> > >
>> > > >> > > > +1 for deprecating APIv2 and APIv3.
>> > > >> > > >
>> > > >> > > > -Zach
>> > > >> > > >
>> > > >> > > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <
>> > > >> mitchell852@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 <
>> > ocket8888@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 <
>> > > rob@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 <
>> > > >> > > > mitchell852@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 <
>> > > >> rob@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 <
>> > > >> > > > > > mitchell852@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 <
>> > > >> > > > rawlin@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
>> > > >> > > > > > > > > > > <Jo...@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 <ra...@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 <
>> > > >> > > > > > ocket8888@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.
>> > > >> > > > > > > > > > >
>> > > >> > > > > > > > > >
>> > > >> > > > > > > > >
>> > > >> > > > > > > >
>> > > >> > > > > > >
>> > > >> > > > > >
>> > > >> > > > >
>> > > >> > > >
>> > > >> > >
>> > > >>
>> > > >
>> > >
>> >
>>
>