Well all I mean by "deprecate" is saying as much in the docs, and possibly returning a warning-level alert. The endpoints would still exist, work as advertised, and (IMO ought to be) translated to Go.
On Thu, Aug 15, 2019 at 1:51 PM Robert Butts <[email protected]> wrote: > @mitchell852 How is that? > > https://cwiki.apache.org/confluence/display/TC/API+Guidelines#APIGuidelines-Deprecation > > > by that I mean not rewriting them to Go and changing the Perl routes to > add a deprecation alert. Although, API promises and what-not aside, I think > we could probably just delete the Perl routes right now because I can't > imagine a valid reason to even be using those endpoints currently. > > >I don't necessarily agree with rewriting deprecated Perl routes in Go. I > think if a route is deprecated in release N, we can remove it in release > N+1 (next major version). > > -1 > > >But if we're going to discuss this immediately, here's my two cents: We've > committed to API versioning. That means that you can't remove an endpoint > that existed in version 1.x without moving to 2.x. So not rewriting all of > the Perl endpoints under `/api/1.x/` would mean that we're committed to > Perl sticking around until API 2.x. I think that's a bad idea, because the > codebase gets much easier to work with when there's only set of source for > a particular component. > > > You can't deprecate an endpoint in ATC version N and remove it in N+1, > because the ATC version does not govern the TO API > > +1 > > The API version the the TC version are _completely separate things_. Even > if the TC major version is increased, the API has its own "version promise" > to avoid breaking clients. > > The problem here is not just breaking a TC CDN operator, it's also breaking > their clients. TC has an API, the whole point of an API is to be able to > program against it reliably. > > The whole point of an "API Promise" is to allow clients, even if their CDN > operator upgrades TO, to write scripts, which continue to work. Which don't > break every few months, every time we delete some random route, because we > decided we didn't think anyone was using it. > > Taking a vote and saying "does anyone here use this route? No? Motion > passes, delete!" completely violates that promise. Most clients, many > operators even, are not on our development or user lists. > > We already don't have as many users and contributors of TC as we'd like. > This kind of thing, deleting random routes from an alleged API, is only > going to lose more TC users and contributors, and make people who consider > it, stop. Nobody wants to use a product that constantly breaks. > > I could understand, if it was this huge massive burden to support these > routes. But it isn't. Versioning isn't hard, we just did it badly in Go > (it's a little better now). And the routes we want to "deprecate" are > mostly small and really not very much work to write and maintain. > > If someone has an old, unused route that's massive, and a huge amount of > logic and work to maintain, I could understand asking to stop supporting > it. In which case, IMO the "least evil" is to still serve the route, and > return a 500 code. I might could even +1 it. Unhappily. Because it is > breaking the API promise, and will break users, and is one more straw on > the camel's back of making a poor, unstable project that people don't want > to use or contribute to. In fact, I've considered proposing just that for > the ATS config endpoints (not because they're work to maintain, but because > they're a lot of duplicate logic that's likely to go untested and be > dangerously error-prone). > > But for endpoints that are a very small amount of work to port and > maintain, it's a big loss to the stability of the project for a very small > development gain. Even if one organization doesn't feel it, it will make us > lose (and not get in the first place) users and contributors, which add > huge value to the project, and we should be trying our best to get, not > drive away. > > @ocket8888 sorry to derail your thread. > > >I could get behind deprecating the ability to mutate capabilities through > the API > > I will say, the version promise applies to the endpoint itself, not the > server. If we want to make the TO Server stop supporting mutating > Capabilities, we can make the API endpoints that do so return 400 codes. > IMO we should be very careful and thoughtful when we do things like that, > because it does break clients, even if we're still technically versioning > correctly. But there are cases where it's worth the cost, to create a > better system. But I'm not close enough to the Capabilities feature to have > an opinion. > > > > > > On Thu, Aug 15, 2019 at 1:16 PM Rawlin Peters <[email protected]> > wrote: > > > On Thu, Aug 15, 2019 at 1:01 PM Robert Butts <[email protected]> wrote: > > > > > > >- don't bother converting `/capabilities/{{name}}` from Perl to Go > > > > > > But we still have to support those routes, until API 1.x is no longer > > > supported, which is far in the future. > > > > > > We should still rewrite deprecated Perl routes in Go, just so we can > get > > > rid of Perl sooner than that. > > > > I don't necessarily agree with rewriting deprecated Perl routes in Go. > > I think if a route is deprecated in release N, we can remove it in > > release N+1 (next major version). We shouldn't be stuck maintaining > > useless endpoints for eternity (especially these ones which don't even > > make sense to support). If removing these deprecated endpoints before > > API 2.x is going to break any users out there, I would be glad to hear > > out their valid use cases for having us support them. > > > > Another example is the `cdns/:name/configs/routing` endpoint. It was a > > half-implemented attempt at breaking up the CRConfig and was not > > returning any valid or useful data at all when I last looked into it. > > Just because it exists in the Perl does not mean we should have to > > take it with us to Go. And the `cachegroup_fallbacks` endpoints, which > > are now supported in cachegroups proper. And the `/riak/stats` > > endpoint, which was mainly for triage purposes during the integration > > of Riak for Traffic Vault. We don't really have a good reason to keep > > those endpoints around IMO. > > > > - Rawlin > > >
