[Cubicweb] Thoughts on RESTfulness and rqlcontroller

Nicolas Chauvat nicolas.chauvat at logilab.fr
Fri Jan 23 23:47:59 CET 2015

Hi List,

For the record, here is the summary of a discussion that took place at Logilab
about a year ago when we decided to allow write access through HTTP and ended up
writing rqlcontroller. I had the thread of emails sitting in my work directory
and thought it would be better to summarize it and archive it in the open on the
mailing list than to lose it.

It all begins with the question "we want write to allow write access, maybe we
should try to merge the ideas / vocabularies of REST and RQL ?".

First consensus is that creating, modifying and deleting objects using a
"GET /?rql={SET,INSERT,DELETE}" would definitely not be RESTFul.

A possible mapping is::

.. csv-table::

   RQL, HTTP, action
   `Any`, `GET /ticket/1234`, return json for ticket
   `INSERT`, `POST /ticket` + request payload, create ticket and return its URL
   `SET`, `PUT /ticket/1234` + request payload, modify ticket attributes and relations
   `DELETE`, `DELETE /ticket/1234`, delete ticket

Here is what an INSERT with POST could look like::

  POST /ticket
  rql=INSERT Ticket T: T title %(mytitle)s, T priority %(mypriority)s, T
    concerns P, T type %(mytype)s WHERE P eid %(peid)s
  mytitle=Mon nouveau ticket

or maybe use directly the attributes and relations as parameters::

  POST /ticket
  title=Mon nouveau ticket

The response to both would be::

  HTTP/1.1 201 Created
  Location: /ticket/98765

Follows a list of open questions and thoughts:

- Is this enough to be useful or is it too limited?

- It is common to need to create several entities in one transaction, or to
  write queries that use RQL functions?

- If the full power of RQL is needed, rqlcontroller is the answer, but then is
  it useful to have a RESTful interface ? Do we need a RESTful interface when we
  have rqlcontroller?

- Is it RESTful to allow to GET on a URL with rql= ? What should happen if the
  rql parameter is INSERT, DELETE or SET something ? Should we add a /rql
  resource on which to GET an arbitrary request. Isn't this rqlcontroller and
  its /rqlio?

- The idea of HTTP verbs is to help the caching infrastructure do its job and to
  get a rough idea of permissions (disallow DELETE for example). Doing
  everything through `POST /rqlio` does not help caching.

- Is there a parallel between rqlcontroller/REST and Sparql/RDF-Fragments?

Nicolas Chauvat

logilab.fr - services en informatique scientifique et gestion de connaissances  

More information about the Cubicweb mailing list