I can see both sides. The 1.x API contract should probably be respected but I hate wasting time rewriting routes with little/no value.
What about something like this? ATCv3 has: api 1.x ~60% Go routes ~40% Perl routes *STOP all work on 1.x* ATCv4 has: api 1.x ~60% Go routes ~40% Perl routes api 2.x 100% Go routes - choose the ones we like from the 1.x's 60% and simply promote them to 2.x - find the "valuable" perl ones that still need to be rewritten and rewrite them to 2.x ATCv5 has: api 2.x api 3.x (at this point we can really overhaul the api and kill 1.x as well (and the perl with it)) This allows us 2 things: 1. we respect the 1.x api contract 2. we won't waste time rewriting perl routes of little/no use as we can be selective what to put in 2.x It really feels like time to just move to 2.x to give us more flexibility, otherwise, our hands are tied by the 1.x api contract. On Thu, Aug 15, 2019 at 2:34 PM Rawlin Peters <rawlin.pet...@gmail.com> wrote: > Again, I disagree with you, yet we are on the same side here. I care > about the community just the same as you do, albeit with somewhat > different values in mind. I don't want to purposely break users by > making unnecessary breaking changes to the API, but I also don't want > to build and support an API that is full of unnecessary footguns. If a > user ends up being broken by the removal of these seemingly useless > capabilities endpoints, then I would question why they were even using > them in the first place because they are not currently used anywhere > in the codebase currently and have no effect whatsoever. IMO we are > more likely to lose users due to having a more dangerous and > unintuitive API than we are by removing endpoints that serve no > purpose. > > - Rawlin > > > On Thu, Aug 15, 2019 at 1:58 PM Robert Butts <r...@apache.org> wrote: > > > > >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 > > >> > > > >
