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/07/16 17:28:06 UTC
Deprecate APIv2 and v3
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>.
One version to rule them all and in the darkness bind them has served us reasonably well historically. When you start splitting things up and accepting you have a compatibility matrix you have to test and maintain your testing costs go up exponentially. I’ve observed many cases in the past that while yes one component can move faster independently, actually getting QA signoff for those changes is more time consuming and expensive. In practice we might behave this way already because the pipeline to production involves people intimate with the code who can make the risk management judgement calls. Changes to the API are an integral part of that and immediate signal that more might be involved than a simple new binary or config tweak. So all-in-all I’m +-0 on it, but only if the actual cost of formalizing that split and its implications of QA costs are understood. As it stands, the ansible lab code is structured and leveraged in a way that would facilitate that should we decide to move forward with it.
Jonathan G
From: Robert O Butts <ro...@apache.org>
Date: Tuesday, July 20, 2021 at 2:18 PM
To: dev@trafficcontrol.apache.org <de...@trafficcontrol.apache.org>
Subject: Re: [EXTERNAL] Re: Deprecate APIv2 and v3
> 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 <mi...@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 <ro...@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 <mi...@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 <ra...@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 <de...@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 <oc...@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 Robert O Butts <ro...@apache.org>.
> we could give each component its own version and maintain a version
compatibility table.
+1
I think you hit on the hard part, if we split things out and version them
separately: the compatibility table. But I think it's easier than it sounds.
Basically, we just need to support 1 version back of apps communicating
between each-other. This is totally unrelated to API versions, for all apps
not just TO, which might serve a public API that non-ATC clients can use.
But even if one app has a bunch of releases and another only has a few, the
"compatibility matrix" for any specific app version is only ever 2 rows
high.
And we're supporting that today anyway, it just isn't as explicit, because
all apps get new versions when the TC version changes. For example, Traffic
Monitor 6.0 and Traffic Stats 2.0 are probably compatible, just because TS
never changes. That just isn't explicit today.
On Tue, Jul 20, 2021 at 2:17 PM Robert O Butts <ro...@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 <mi...@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 <ro...@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 <mi...@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 <ra...@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 <de...@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 <oc...@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.
>> > > >> > > > > > > > > > >
>> > > >> > > > > > > > > >
>> > > >> > > > > > > > >
>> > > >> > > > > > > >
>> > > >> > > > > > >
>> > > >> > > > > >
>> > > >> > > > >
>> > > >> > > >
>> > > >> > >
>> > > >>
>> > > >
>> > >
>> >
>>
>
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by ocket 8888 <oc...@gmail.com>.
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>.
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 "Gray, Jonathan" <Jo...@comcast.com.INVALID>.
> 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 <zr...@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 <de...@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>.
I have a link to the mailing list discussion:
https://lists.apache.org/thread.html/b857afc7b52e72b2e60ebb3eb594b6fa5dd0ed3c9af5a17b58ee4a99%40%3Cdev.trafficcontrol.apache.org%3E
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 <zr...@apache.org>
> > >> wrote:
> > >> >
> > >> > > > Does API 4.x exist before 6.0?
> > >> > > According to the most recent docs, yes.
> > >> >
> > >>
> >
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> > >> >
> > >> > Those are the docs for the master branch.
> > >> > There is no mention of API 4.x in the ATC 5.1.2 docs:
> > >> > https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html
> > >> >
> > >> > -Zach
> > >> >
> > >> >
> > >> > On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
> > >> > <Jo...@comcast.com.invalid> wrote:
> > >> >
> > >> > > According to the most recent docs, yes.
> > >> > >
> > >>
> >
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> > >> > >
> > >> > > Jonathan G
> > >> > >
> > >> > > From: Dave Neuman <ne...@apache.org>
> > >> > > Date: Tuesday, July 27, 2021 at 10:59 AM
> > >> > > To: dev@trafficcontrol.apache.org <de...@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 Rawlin Peters <ra...@apache.org>.
> Isn't this email almost like a survey? Anyone doing API work is probably on this ML or should be.
That's kind of my point, not many people doing external development
against the TO API are chiming in, but the majority of TO developers
are in favor of this proposal.
> Brennan, do you have a link to that discussion? If it wasn't on list then it didn't happen ;)
That came from this long thread we had about the TO API v2 transition:
https://lists.apache.org/thread.html/0c59606029f6363dc19bbefa4cddd698891d4dad9f142f09a14c89fe%40%3Cdev.trafficcontrol.apache.org%3E
The TO API v1 removal was pushed out of ATC 5.0 despite the agreement
that was made.
I'd be ok with only removing TO API v2 in ATC 7.0 and removing TO API
v3 in 7.1 or 8.0 (whatever is soonest), but we really need to get to
the point where we only support a single major TO API version so that
we can eliminate all the tech debt and cruft that comes with
supporting so many different versions.
- Rawlin
Re: [EXTERNAL] Re: Deprecate APIv2 and v3
Posted by Dave Neuman <ne...@apache.org>.
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 <zr...@apache.org>
> >> wrote:
> >> >
> >> > > > Does API 4.x exist before 6.0?
> >> > > According to the most recent docs, yes.
> >> >
> >>
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> >> >
> >> > Those are the docs for the master branch.
> >> > There is no mention of API 4.x in the ATC 5.1.2 docs:
> >> > https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html
> >> >
> >> > -Zach
> >> >
> >> >
> >> > On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
> >> > <Jo...@comcast.com.invalid> wrote:
> >> >
> >> > > According to the most recent docs, yes.
> >> > >
> >>
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> >> > >
> >> > > Jonathan G
> >> > >
> >> > > From: Dave Neuman <ne...@apache.org>
> >> > > Date: Tuesday, July 27, 2021 at 10:59 AM
> >> > > To: dev@trafficcontrol.apache.org <de...@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 <zr...@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>.
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 <zr...@apache.org>
>> wrote:
>> >
>> > > > Does API 4.x exist before 6.0?
>> > > According to the most recent docs, yes.
>> >
>> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
>> >
>> > Those are the docs for the master branch.
>> > There is no mention of API 4.x in the ATC 5.1.2 docs:
>> > https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html
>> >
>> > -Zach
>> >
>> >
>> > On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
>> > <Jo...@comcast.com.invalid> wrote:
>> >
>> > > According to the most recent docs, yes.
>> > >
>> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
>> > >
>> > > Jonathan G
>> > >
>> > > From: Dave Neuman <ne...@apache.org>
>> > > Date: Tuesday, July 27, 2021 at 10:59 AM
>> > > To: dev@trafficcontrol.apache.org <de...@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 <zr...@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 <oc...@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 <ro...@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>.
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 <zr...@apache.org>
> wrote:
> >
> > > > Does API 4.x exist before 6.0?
> > > According to the most recent docs, yes.
> >
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> >
> > Those are the docs for the master branch.
> > There is no mention of API 4.x in the ATC 5.1.2 docs:
> > https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html
> >
> > -Zach
> >
> >
> > On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
> > <Jo...@comcast.com.invalid> wrote:
> >
> > > According to the most recent docs, yes.
> > >
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> > >
> > > Jonathan G
> > >
> > > From: Dave Neuman <ne...@apache.org>
> > > Date: Tuesday, July 27, 2021 at 10:59 AM
> > > To: dev@trafficcontrol.apache.org <de...@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 <zr...@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 <oc...@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 <ro...@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 Rawlin Peters <ra...@apache.org>.
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 <zr...@apache.org> wrote:
>
> > > Does API 4.x exist before 6.0?
> > According to the most recent docs, yes.
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
>
> Those are the docs for the master branch.
> There is no mention of API 4.x in the ATC 5.1.2 docs:
> https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html
>
> -Zach
>
>
> On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
> <Jo...@comcast.com.invalid> wrote:
>
> > According to the most recent docs, yes.
> > https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
> >
> > Jonathan G
> >
> > From: Dave Neuman <ne...@apache.org>
> > Date: Tuesday, July 27, 2021 at 10:59 AM
> > To: dev@trafficcontrol.apache.org <de...@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 <zr...@apache.org> wrote:
> >
> > > +1 for deprecating APIv2 and APIv3.
> > >
> > > -Zach
> > >
> > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <mi...@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 <oc...@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 <ro...@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 <ro...@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>.
> > Does API 4.x exist before 6.0?
> According to the most recent docs, yes.
https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
Those are the docs for the master branch.
There is no mention of API 4.x in the ATC 5.1.2 docs:
https://traffic-control-cdn.readthedocs.io/en/v5.1.2/api/index.html
-Zach
On Tue, Jul 27, 2021 at 11:29 AM Gray, Jonathan
<Jo...@comcast.com.invalid> wrote:
> According to the most recent docs, yes.
> https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
>
> Jonathan G
>
> From: Dave Neuman <ne...@apache.org>
> Date: Tuesday, July 27, 2021 at 10:59 AM
> To: dev@trafficcontrol.apache.org <de...@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 <zr...@apache.org> wrote:
>
> > +1 for deprecating APIv2 and APIv3.
> >
> > -Zach
> >
> > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <mi...@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 <oc...@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 <ro...@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 <ro...@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>.
According to the most recent docs, yes. https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
Jonathan G
From: Dave Neuman <ne...@apache.org>
Date: Tuesday, July 27, 2021 at 10:59 AM
To: dev@trafficcontrol.apache.org <de...@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 <zr...@apache.org> wrote:
> +1 for deprecating APIv2 and APIv3.
>
> -Zach
>
> On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <mi...@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 <oc...@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 <ro...@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 <ro...@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 Dave Neuman <ne...@apache.org>.
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 <zr...@apache.org> wrote:
> +1 for deprecating APIv2 and APIv3.
>
> -Zach
>
> On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <mi...@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 <oc...@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 <ro...@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 <ro...@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>.
+1 for deprecating APIv2 and APIv3.
-Zach
On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <mi...@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 <oc...@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 <ro...@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 <ro...@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 Jeremy Mitchell <mi...@gmail.com>.
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 <oc...@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 <ro...@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 <mi...@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 <ro...@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 <ra...@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>.
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 <ro...@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 <mi...@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 <ro...@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 <ra...@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 Robert O Butts <ro...@apache.org>.
> 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 <mi...@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 <ro...@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 <mi...@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 <ra...@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 <de...@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 <oc...@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 on syncing the TO API version to the ATC version.
In theory, we could have ATC releases that don't even change the TO
API at all (I might be dreaming here), so revving the TO API version
in those releases wouldn't make sense. It would definitely be easier
to remember which version of ATC introduced which TO API version if
they matched, but, unfortunately, that is just something we have to
remember when dealing with versioned APIs.
> All good points but also consider this, ATC is version 5.x, for example, so
> all the components are version 5.x, right?
Not necessarily. If we were more disciplined about it, we could give
each component its own version and maintain a version compatibility
table. Also, we have some components (like Traffic Stats) which go
many ATC releases without actually changing at all, but their rpm
version is still updated. Because the rpm version is updated, it
causes the outside observer to think that the component was actually
changed and that they should upgrade. However, upgrading is actually
unnecessary work in those cases.
Continuing along these lines, we could give TO its own version that
mostly matched its latest API version. For example, the TO API version
is currently 4.0. We could simply declare that the TO version is
4.0.0. If we introduce a new minor API version (4.1), well then that
would be a minor change, and the TO version would be updated to 4.1.0.
After that, if we only introduced bug fixes or other improvements that
didn't affect the API, we would update the TO version to 4.1.1.
Having our component versions match the ATC release version is just a
convention that we've chosen to follow as a project, but we can
definitely change that. In fact, if we gave components their own
version, that would allow us to more easily release components by
themselves and get them into production faster, rather than waiting
for the ATC release in order to upgrade everything or building from
master periodically. We've been kicking around the idea of breaking
out components into their own repos, and I think we'd probably need to
give them their own versions and releases at that point anyways.
- Rawlin
On Tue, Jul 20, 2021 at 1:44 PM Jeremy Mitchell <mi...@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 <ro...@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 <mi...@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 <ra...@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 <de...@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 <oc...@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>.
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 <ro...@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 <mi...@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 <ra...@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 <de...@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 <oc...@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 Robert O Butts <ro...@apache.org>.
> 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 <mi...@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 <ra...@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 <de...@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 <oc...@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>.
-1
Syncing things to the ATC major rev is fine if you never run anything prior to an official release and after the very first minor rev it never changes. Both of these are not true in my experience. The third major problem of being mid-flight during an upgrade I assume is a non-issue because you’d always maintain what was available in the first release of the previous major project rev. API version management is a combination of discipline and implementation. We’ve debated consolidating at length before and that wasn’t the decision at the time albeit open to discussion again. As a 3rd party code writer I’m not a fan because if for feature reasons I’m forced to code at latest version available as opposed to the last one that was released, I have no ability at that point to hold the API stable at all from rev to rev. Additionally, by locking the two together, I’m forced to basically overhaul code at every release. I think I understand that the desire is only to move it forward, if necessary, but I can’t think of a situation where that wouldn’t be the case as our data model and feature sets are linked so hard to the major rev of the project. If the implementation costs of backward compatibility are what’s hard, there does exist extra libraries https://github.com/rob05c/apiver for example that can make the most challenging parts easier.
Historical context (it’s a lot):
* https://lists.apache.org/thread.html/504b33b9c7b037a3b17a44613b326e0bdefd191cb7e62c0aca9e9515%40%3Cdev.trafficcontrol.apache.org%3E
* https://lists.apache.org/thread.html/c2d93fd6fb3b48a69b0c8fde55de8558d9878797400d9f63537f38ce%40%3Cdev.trafficcontrol.apache.org%3E
* https://lists.apache.org/thread.html/1a42a2192a81fc4d76639ccd10761b6b73c31345a63715bb8aa86e4e%40%3Cdev.trafficcontrol.apache.org%3E
Jonathan G
From: Jeremy Mitchell <mi...@gmail.com>
Date: Tuesday, July 20, 2021 at 1:00 PM
To: dev@trafficcontrol.apache.org <de...@trafficcontrol.apache.org>
Subject: Re: [EXTERNAL] Re: Deprecate APIv2 and v3
^^ 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 <ra...@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 <de...@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 <oc...@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>.
^^ 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 <ra...@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 <de...@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 <oc...@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>.
> 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 <de...@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 <oc...@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>.
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 <de...@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 <oc...@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: Deprecate APIv2 and v3
Posted by Rawlin Peters <ra...@apache.org>.
+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 <oc...@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.