>We should be able to make exceptions to "the rules" in exceptional cases. Deleting useless routes that provide no purpose to the system is what I would consider an exceptional case.
As above, I would consider an exception case where it's an unreasonably huge amount of code and work, or danger. I do not consider it "exceptional" for small, easy routes. > We should support API promises where they make sense and not get too carried away with the "rules" where it doesn't make sense. -1. It does make sense here, it makes sense to maintain a stable project, to attract users and committers. It's not about "following the rules," it's about not breaking users. > Let's not let this thread devolve into API versioning. I agree, it should be a separate thread, if you want to raise this issue again. But you can't state strong opinions that have huge impact (IMO negatively) on the project, and then tell other people not to comment. That isn't really fair to an open community. On Thu, Aug 15, 2019 at 1:51 PM Robert Butts <r...@apache.org> 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 <rawlin.pet...@gmail.com> > wrote: > >> On Thu, Aug 15, 2019 at 1:01 PM Robert Butts <r...@apache.org> 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 >> >
