> > 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 <jonathan_g...@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 <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. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
