According to the most recent docs, yes. https://traffic-control-cdn.readthedocs.io/en/latest/api/index.html#api-v4-routes
Jonathan G From: Dave Neuman <neu...@apache.org> Date: Tuesday, July 27, 2021 at 10:59 AM To: dev@trafficcontrol.apache.org <dev@trafficcontrol.apache.org> Subject: Re: [EXTERNAL] Re: Deprecate APIv2 and v3 Does API 4.x exist before 6.0? I am worried about basically telling our users that before they can go to 6.x they have to get off API 1.x but the latest at that point is 3.x so then we are turning around and saying they have to update again. I would prefer if we gave more time and did 2.0 now and 3.0 in our next release. I am not going to -1 because ultimately it is not going to impact me as much as those that have already shared opinions, but I did want to make sure we aren't being unfair to our users. Thanks, Dave On Mon, Jul 26, 2021 at 4:40 PM Zach Hoffman <zrhoff...@apache.org> wrote: > +1 for deprecating APIv2 and APIv3. > > -Zach > > On Tue, Jul 20, 2021 at 3:28 PM Jeremy Mitchell <mitchell...@gmail.com> > wrote: > > > sorry about that. i'm +1 on deprecating APIv2 and APIv3 in the fashion > you > > mentioned. > > > > On Tue, Jul 20, 2021 at 2:39 PM ocket 8888 <ocket8...@gmail.com> wrote: > > > > > I don't really want to propose anything more complex than deprecating > > APIv2 > > > and APIv3 in this thread. Which isn't to say that I don't have > opinions > > on > > > all of this, but it's starting to confuse the point when people are > > giving > > > +1s and -1s on things besides the thread subject. > > > > > > On Tue, Jul 20, 2021 at 2:17 PM Robert O Butts <r...@apache.org> wrote: > > > > > > > > so really TO (api) seems to have many versions > > > > > > > > The Traffic Ops application has a single project/app version. The TO > > > > Application "serves" multiple API Versions, which are unrelated to > that > > > > application version. TO doesn't "have" many versions, it has one > > > version. A > > > > particular Traffic Ops version "10" might serve API versions X,Y,Z. > But > > > > those API versions aren't "part" of the Traffic Ops Versions. There > > > exists > > > > no "Traffic Ops version 10" which serves any other API versions. And > > > there > > > > might exist other Traffic Ops versions which also serve X,Y,Z. So, TO > > > only > > > > has one version, "10." X,Y,Z are unrelated to 10, except that 10 is > > > > documented as serving X,Y,Z. > > > > > > > > > ATC is version 5.x, for example, so all the components are version > > 5.x, > > > > right? > > > > > > > > As an aside, IMO having separate application versions would make a > lot > > of > > > > sense and make a lot of things easier. I don't want to push for that > > > right > > > > now, but something to think about. Maybe part of the version after > the > > > > project, e.g. ATC could be Version 10.11 and Traffic Ops could have > its > > > own > > > > application version 5.7, so Traffic Ops would have the complete > version > > > > "atc-10.11-to-5.7-hash-abc123.rpm" or whatever. I think that might > make > > > it > > > > clearer when one app hasn't changed even if the project did, > especially > > > > with our apps that don't change very often. Something to think about. > > > > > > > > > > > > > > > > On Tue, Jul 20, 2021 at 1:44 PM Jeremy Mitchell < > mitchell...@gmail.com > > > > > > > wrote: > > > > > > > > > All good points but also consider this, ATC is version 5.x, for > > > example, > > > > so > > > > > all the components are version 5.x, right? meaning the TO component > > > (aka > > > > > the TO api) is.... version 5.x.... :) > > > > > > > > > > so really TO (api) seems to have many versions (5.x inherited from > > the > > > > > project and 2.x, 3.x, 4.x, the versions of the "interface"). yes, > > > > > confusing... > > > > > > > > > > > > > > > > > > > > On Tue, Jul 20, 2021 at 1:32 PM Robert O Butts <r...@apache.org> > > wrote: > > > > > > > > > > > > Also, after years of API confusion, is it time to simply sync > the > > > ATC > > > > > > > version with the API version (brennan has touched on this in > the > > > > past) > > > > > > > starting with our "next" API version. So instead of APIv5, we'd > > > just > > > > > jump > > > > > > > to APIv7. ex: > > > > > > > > > > > > I strongly disagree with "synchronizing" the API and project > > version. > > > > The > > > > > > idea that they need to be the same is deeply confused about what > > they > > > > > are, > > > > > > and making them the same will reinforce that confusion with the > > > people > > > > > who > > > > > > are confused. > > > > > > > > > > > > The project version and the API version are completely > independent > > > and > > > > > > unrelated things. The idea that they need to be versioned > together > > > and > > > > > are > > > > > > somehow the same thing is incredibly confused and mistaken about > > the > > > > > > fundamental idea of what an API is and what a code project is. > > > > > > > > > > > > The API is the API. The project is the project. An API is an > > > > Application > > > > > > Programming Interface: an interface, like an electric outlet or a > > > water > > > > > > faucet connection. The Traffic Control project is a code > project: a > > > > > > collection of applications, written in code, to do a thing, in > this > > > > case > > > > > a > > > > > > CDN. > > > > > > > > > > > > These are completely, entirely, totally different things. It > would > > be > > > > > like > > > > > > working for a company that sells both laptops and capacitors, and > > > > saying, > > > > > > "Our capacitors and laptops should have the same serial numbers, > > > > because > > > > > > they both contain iron atoms." > > > > > > > > > > > > Yes, the code in the project serves certain APIs. But the two > > things > > > > are > > > > > > completely independent. Giving them the same version will > reinforce > > > the > > > > > > wrong and confused belief that they're somehow the same thing, > when > > > > > > literally the only thing they have in common as ideas is that > > they're > > > > two > > > > > > version numbers published by Apache Traffic Control. > > > > > > > > > > > > Moreover, All Traffic Control applications will always have to > > serve > > > at > > > > > > least one major version back, in order to make it possible to > > > upgrade. > > > > So > > > > > > the confused idea that they're somehow the same will be made even > > > more > > > > > > confusing, because now people think "The API is the same as the > > > > Project, > > > > > > and the version proves it, but the project has to serve multiple > > > APIs." > > > > > > Making people even more confused. > > > > > > > > > > > > In fact, I'm inclined to think making the versions completely > > > different > > > > > > schemes, such as one being letters and the other numbers, would > > help > > > > > reduce > > > > > > the confusion, and make it more clear that the two versioned > things > > > are > > > > > > completely unrelated. > > > > > > > > > > > > > > > > > > On Tue, Jul 20, 2021 at 1:00 PM Jeremy Mitchell < > > > mitchell...@gmail.com > > > > > > > > > > > wrote: > > > > > > > > > > > > > ^^ I'm good with this. > > > > > > > > > > > > > > Also, after years of API confusion, is it time to simply sync > the > > > ATC > > > > > > > version with the API version (brennan has touched on this in > the > > > > past) > > > > > > > starting with our "next" API version. So instead of APIv5, we'd > > > just > > > > > jump > > > > > > > to APIv7. ex: > > > > > > > > > > > > > > ATCv7 supports APIv7 (to get inline with ATC version) and APIv4 > > > (the > > > > > api > > > > > > > version from ATCv6) > > > > > > > ATCv8 supports APIv8 and APIv7 > > > > > > > etc > > > > > > > > > > > > > > but then i guess that begs the question, if we bump the major > ATC > > > > > version > > > > > > > for another reason (big feature or something), does that mean > we > > > have > > > > > to > > > > > > > bump the API version if not really necessary just to keep ATCv > == > > > > APIv? > > > > > > > > > > > > > > jeremy > > > > > > > > > > > > > > On Mon, Jul 19, 2021 at 1:08 PM Rawlin Peters < > raw...@apache.org > > > > > > > > wrote: > > > > > > > > > > > > > > > > What kind of backward compatibility expectation are we > aiming > > > for > > > > > > here? > > > > > > > > With 1.x we were coming from 5+ years of backward > compatibility > > > > > > > > > > > > > > > > I don't think we ever intended for API 1.x to live for so > long, > > > but > > > > > we > > > > > > > > also never promised an agreed-upon amount of time for > backwards > > > > > > > > compatibility. I think the intention is that we'd like to > have > > > one > > > > > > > > major release cycle where both major API versions are > supported > > > (in > > > > > > > > order for clients to have a transitionary period), then we > are > > > free > > > > > to > > > > > > > > remove the deprecated API version in the following release. > The > > > > > amount > > > > > > > > of time we remain backwards-compatible should really depend > on > > > how > > > > > > > > long the release cycles are, which we're aiming for > quarterly. > > > > > > > > > > > > > > > > I agree it is a lot of headache to update 3rd party tooling > as > > > API > > > > > > > > versions are deprecated and removed (which is why I'm hoping > we > > > > don't > > > > > > > > introduce another major API version very soon), but hopefully > > the > > > > > vast > > > > > > > > majority of cases are simply updating the URLs from 2.0 or > 3.0 > > to > > > > > 4.0, > > > > > > > > since there should only be a small number of breakages from > 2.0 > > > to > > > > > 4.0 > > > > > > > > (mostly servers-related routes) that would actually require > > > > changing > > > > > > > > more than just the URL. Migrating from 1.x has probably been > > more > > > > > > > > difficult since we dropped a lot of redundant routes. > > > > > > > > > > > > > > > > - Rawlin > > > > > > > > > > > > > > > > > > > > > > > > - Rawlin > > > > > > > > > > > > > > > > On Mon, Jul 19, 2021 at 11:43 AM Gray, Jonathan > > > > > > > > <jonathan_g...@comcast.com.invalid> wrote: > > > > > > > > > > > > > > > > > > What kind of backward compatibility expectation are we > aiming > > > for > > > > > > here? > > > > > > > > With 1.x we were coming from 5+ years of backward > compatibility > > > and > > > > > now > > > > > > > it > > > > > > > > seems like we’re aiming for < 1 year with rotation at every > > major > > > > > rev. > > > > > > > > That’s a lot of headache for 3rd party tooling support to > > > > constantly > > > > > be > > > > > > > > changing regardless if that means you’re upgrading SDK > > > dependencies > > > > > or > > > > > > > raw > > > > > > > > HTTP calls. > > > > > > > > > > > > > > > > > > Jonathan G > > > > > > > > > > > > > > > > > > From: Rawlin Peters <raw...@apache.org> > > > > > > > > > Date: Friday, July 16, 2021 at 11:54 AM > > > > > > > > > To: dev@trafficcontrol.apache.org < > > > dev@trafficcontrol.apache.org > > > > > > > > > > > > > > Subject: [EXTERNAL] Re: Deprecate APIv2 and v3 > > > > > > > > > +1 on deprecating API v2-3 with the release of ACTv6 and > > > removing > > > > > > them > > > > > > > > > in ATCv7. Hopefully we won't need a TO API v5 very soon so > we > > > can > > > > > > have > > > > > > > > > a break from the API instability. > > > > > > > > > > > > > > > > > > +1 on not requiring every v2 and v3 endpoint to return > > > > deprecation > > > > > > > > > notices. I think just mentioning it on the mailing list, > the > > > > > > > > > changelog, and the docs should cover it. Updating all the > > v2/v3 > > > > > > > > > endpoints to return deprecation notices would be quite a > lot > > of > > > > > code > > > > > > > > > change with very little benefit IMO. However, for certain > > > > endpoints > > > > > > > > > that have no v4 equivalent, we are returning deprecation > > > notices > > > > > > (e.g. > > > > > > > > > cachegroup parameters). > > > > > > > > > > > > > > > > > > - Rawlin > > > > > > > > > > > > > > > > > > On Fri, Jul 16, 2021 at 11:28 AM ocket 8888 < > > > ocket8...@gmail.com > > > > > > > > > > > > wrote: > > > > > > > > > > > > > > > > > > > > With the release of APIv4 in ATCv6, should we > > simultaneously > > > > > > > deprecate > > > > > > > > > > APIv2 and APIv3? I think so, that'll mean we can remove > > them > > > in > > > > > > > ATCv7, > > > > > > > > > > whereupon the stable API 4.0 will have existed for a full > > > major > > > > > > rev, > > > > > > > > and > > > > > > > > > > APIv5 will ostensibly be released (if not sooner, since > we > > > > could > > > > > do > > > > > > > > that > > > > > > > > > > e.g. in a 6.1). > > > > > > > > > > > > > > > > > > > > If so, we should also discuss what that will mean > > materially. > > > > > With > > > > > > > > > > endpoints that disappear between API versions we have > them > > > > return > > > > > > > > > > warning-level alerts that indicate they won't be > available > > on > > > > > > > upgrade, > > > > > > > > but > > > > > > > > > > for APIv1 as a whole we didn't issue any kind of formal > > > notice > > > > > > afaik, > > > > > > > > not > > > > > > > > > > even a changelog entry. I think the right answer is > > somewhere > > > > > > between > > > > > > > > these > > > > > > > > > > - a changelog entry and notices on the APIv2 and APIv3 > > > > reference > > > > > > > > sections > > > > > > > > > > of the documentation. I don't think it's necessary to > > mention > > > > on > > > > > > each > > > > > > > > > > endpoint that the entire API version is deprecated, > either > > in > > > > the > > > > > > > > > > documentation or in the API through Alerts. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
