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