[PATCH 0/7] REST API (v2)

[Finucane, Stephen]

On 20 Oct 23:34, Finucane, Stephen wrote:
> > I did a full pass on the REST API I had and extracted a documented subset
> > that
> > should be easy to extend in the future.
> > 
> >   http://patchwork-freedesktop.readthedocs.org/en/latest/api.html
> > 
> > A list of entry points is available, that's the basic documentation needed.
> > More will be added later (describe the 'related' GET parameter, how lists
> > of
> > objects work, ordering, some more details about the various fields, ...)
> > 
> > On top of exposing the basic objects, later patches add the concept of
> > events
> > to the db and expose them in the API. The first event here is
> > 'series-new-revision', an event created when patchwork has received a new
> > version of a series. This event can be listened to (well, using polling
> > atm) to
> > trigger tests on an incoming series.
> > 
> > FWIW, the REST API is documented using sphinxcontrib-httpdomain[1], a bit
> > quirky but does the job.
> > 
> > --
> > Damien
> > 
> > [1] https://pythonhosted.org/sphinxcontrib-httpdomain/
> 
> I'm interested in hearing other peoples perspectives on this. I don't want to
> undermine or make little of anyone's work here and I really am a fan of the
> open API movement and REST in particular. However, as previously stated,
> there is an XML-RPC API available for use and it doesn't require adding a lot
> of new code that needs to be maintained, not to mention new libraries and the
> need to develop and distribute new clients. This particular change seems like
> a combination of reluctance to learn how XML-RPC APIs work and unwillingness
> to fix issues with the existing API. We could do everything that is
> accomplished in the first six patches of this series in approximately 50
> lines of code. REST may be the current API du jour, but XML-RPC isn't the
> complicated beast that is SOAP. I honestly don't think REST brings enough to
> the table *for our use cases* to justify the move.

So after working with the XML-RPC API for 'git-pw' [1] (I was made aware of
some similar effort by Damien only yesterday. We're likely going to combine
efforts here when the time is right), I think I can now answer this myself.
The issues that I've seen with the XML-RPC API are such:

* No proper error messages
  The API returns empty bodies ([] or {}) on error. If I receive this, do I
  assume the request was incorrect or that the entity just doesn't exist?
* Poor documentation
  I've actually resolved most of this in recent changes [2], but the sad fact
  is that REST is the API de jour and RPC just doesn't get that much airtime
  any more (I can't find the resource, but I think the method that patchwork
  uses to add XML-RPC to Django was taken from a blog written in ~2008 - the
  same year Airbnb - which apparently owns SF now - was founded)
* General unfriendliness
  Me: I want to list patches with one of two states
  API: Sorry bud, no can do. You'll need two requests for that.
  Me: :(
  ---
  Me: I want to list all patches belonging to the patchwork project
  API: Ummm...I can't do anything with the project name. What's the (obscure)
    project ID again?
  Me: :(
  ---
  Me: I want to do wildcard search by names
  API: Sure, just go read this documentation on Django model keywords
  Me: :'(
* Other stuff I've forgotten
  There's more, but I appear to have blocked it out

These issues are significant enough that I think we'd need to completely
rework the API to enable tools like 'git-pw' to work. That's going to cause
all sorts of issues, breaking peoples tools etc. so I don't think it's
practical. Instead, I propose following through on Damien's suggestions and
implementing a REST API.

I've discussed this in private with Damien, and we've agreed to put
together a proposal for how the end product will look. This is hosted on an
Etherpad instance [3] (OpenStack-habits) that anyone can contribute their
thoughts to. I don't have an ETA for this, but I'd like to get something
prototyped before the end of the year.

The one major concern right now is around frameworks. Both Damien's
implementation and my prototypes from some time back [4] rely on Django REST
Framework. This isn't available in the repos of many enterprise Linux distros
so it may not be possible to use this. Discussion is ongoing here.

Cheers,
Stephen

[1] https://www.github.com/stephenfin/git-pw
[2] https://lists.ozlabs.org/pipermail/patchwork/2015-October/001867.html
[3] https://pad.riseup.net/p/patchwork-rest-api
[4] https://github.com/stephenfin/patchwork/tree/draft/rest-api

> Stephen
> _______________________________________________
> Patchwork mailing list
> Patchwork at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork