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