Should the API strive to be RESTful?

[cboulanger]

Taking this question from https://github.com/diegodlh/zotero-cita/pull/148 since it concerns an important API design decision.

Currently, the API works more like a RPC endpoint, as it treats the URL as a "method" and expects POSTed JSON data as parameters for this method. We do have two GET endpoints, but they might as well accept a POST request.

The question is if the API should instead strive to be RESTful, i.e. use the HTTP verbs to express intent, rather than through the URI - i.e. DELETE /zotero-api-endpoint/item?libraryID=XXX&itemKey=XXX instead of POST /zotero-api-endpoint/item/delete with the parameters in the POST data (as it is now)

PRO:

• Seems like best practice for a server that handles HTTP requests
• This would allow to model the API on the zotero.org Web API and extend it with custom API methods

CON:

• "Normal" RESTful servers handle dynamic values in the URL such as PATCH /zotero-api-endpoint/{libraryID}/{itemKey}, and the Zotero server doesn't. This means that parameters have to be moved into the querystring, which leads to ugly URLs and makes request data validation more complicated
• complex intents have to be squeezed into the boxes of HTTP verbs, even when it doesn't really make sense

[Dominic-DallOsto]

Yeah, I'll have to think about this a bit.

Just as a starter, do you know how accessing the query string works in the endpoint? Does it just get converted to post data?

[cboulanger]

I do not. We would have to look at the source and/or could create some ad-hoc endpoint in the "run javascript" console to see what is passed to the endpoint handler.

[Dominic-DallOsto]

Here it says that the post data in the function comes from the query string if it's a get request, otherwise from the body post data if it's a post request. It might not be possible to mix the two? But I'll check this at some point.

[diegodlh]

Hi! It doesn't seem to be documented on the page mentioned above, but according to the source code there would be three ways of specifying the endpoint object's init method.

The way mentioned on the webpage above is an init method that takes two arguments: the postData (which as mentioned by you includes either the query string for GET requests, or the request body for POST requests), and a sendResponseCallback function.

However, the init method may also take a single argument, in which case it is passed an object which seems to include, among others, both the query string and the post data. This method should either return a [statusCode, contentType, body] array, or a promise. I've just made a quick test and it seems to work.