Request for comments: Adding a GraphQL API

[Thomas De Schampheleire]

Hi Søren,

On Thu, Sep 8, 2016 at 3:49 PM, Søren Løvborg <sorenl at unity3d.com> wrote:
> For a while, there's been some discussion about Kallithea's API design. It
> seems clear that nobody is really happy with the current JSON-RPC API, which
> is also in its current form quite limited.
>
> There's been talk about adding a REST-like API, either in a separate API
> namespace or in the same namespace as the HTML user interface.
>
> In the latter case, a request like GET /repo/pull-request/42 would return
> HTML by default, but JSON if the request came with an "Accept:
> application/json" HTTP header. While the idea has a conceptual purity to it,
> I'm not convinced by the feasibility of actually having both a REST-like API
> and the HTML UI share the same URL namespace. The two are quite different
> models, which we've learned the hard way in Kallithea with its use of
> _method overrides to fake DELETE and PUT requests from an HTML form (which
> can only generate GET and POST), a hack which has caused numerous headaches.
> Looking across the web, I know of no large website that tries to fit both
> REST API and browser access into the same URL namespace; they all maintain a
> separate API namespace.
>
> Even then, deciding to add a new API under e.g. "/_api/" still leaves a lot
> of open questions, because the concept of a REST-like API is somewhat vague.
> For instance, it's quite straightforward to say "to request a PullRequest
> resource by ID, make a GET request to /_api/pull_requests/42", but a
> PullRequest consists of a number of "sub-resources", like the PR owner (a
> "User" object), reviewers, changesets, comments, etc.
>
> One extreme is to only return IDs (or URLs, if you want to be more
> REST-like) for each of these sub-resources. If the caller wants e.g.
> changeset details, they'll then have to issue a long series of follow-up
> requests to fetch data about each of them, resulting in unacceptable
> performance. For this reason, most REST-like APIs return a wide selection of
> sub-resource data inline. This, on the other hand, often produces way too
> much data, again resulting in bad performance. See e.g. the GitHub API
> example for requesting a list of PRs for a repository:
> https://developer.github.com/v3/pulls/#response (and note that in that
> example, there's only ONE pull request in the resulting list).
>
> At Unity, we've been experimenting with adding GraphQL support to Kallithea.
> For those who (like me just a few months ago) haven't heard of GraphQL, it's
> a standard for querying structured data (developed by Facebook), which tries
> to solve these problems.
>
[..]
>
> I'd like to learn if there's general interest in this approach, and to see
> if people feel this would fit their API needs. (Obviously, having a GraphQL
> API doesn't preclude us from also having a REST-like API either, but it
> might make it redundant.)
>
> My current proof-of-concept is not quite presentable yet, but I hope to have
> something to share soon-ish.
>
> More info about GraphQL can be found here: http://graphql.org/
>

Thanks for this clear write-up, very helpful.

Not being a REST-nor-any-alternative expert, GraphQL definitely looks
an interesting approach. I see no reason why it could not fit
Kallithea.

In case it is helpful, here are my current API needs:
- be able to submit a pull request via API, after having pushed
commits to Kallithea. We want to be able to indicate the range of
commits that should be part of the pull request. Until now, we are
using PullRequestsCtroller directly, exposed as API via an .ini file
setting, by sending POST data along.
- be able to query/find a user 'handle' (something we can use to
indicate reviewers of a PR) based on some search data, perhaps a name,
username or e-mail.
- be able to retrieve information about a PR, much like what you
described above in the example

While the second two cases are about retrieving info, the first is
about submitting something. Looking at the GraphQL spec, this should
work fine too, using a 'mutation' operation instead of 'query'.

So, I'm looking forward to seeing more about this...

Thanks,
Thomas