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