Is something like "answers/{id}/downvote" considered RESTful?

Question

Looking at Stack Exchange API docs, I see methods like answers/{id}/downvote answers/{id}/downvote/undo comments/{id}/delete.

Should this be considered a RESTful API? (The docs does not mention the word REST, but anyway it at least resembles a RESTful design, and here and there it's assumed to be so).

I'm asking because, while those methods look self-explanatory and "natural", I'm not sure if they comply with the REST philosophy. For one thing, they write the intented verb (the action to be done with the resource) as part of the URL. Instead, REST proponents argue (here and here and here), we should restrict to the four HTTP verbs. If you think you need "more verbs", then you are not enlightened yet. When you want to perform multiple actions on a resource, then you should use (they say) a single URL... and embed that "extra data" (what you want to do!) in the POST body... (which smells hideous to me in several levels, but anyway, I know little about REST).

Furthermore, the SE API, in my last example, even uses the verb "delete" in the URL, instead of using the (for once) available method DELETE...

Then, am I right in assuming that this is really not RESTful, or at least it's an "impure" (pragmatic and nice, I'd say) design, from the REST point of view?

If so, what would be the RESTful way? Instead of answers/{id}/downvote one should do something like POST answers/{id} and in the body place something like { action: "downvote" }?

Answer 1

There's one thing you need to qualify when talking about whether something is RESTFul: are you talking about the concept of REST as defined in Roy Fielding's thesis OR are you talking about the REST conventions that are built around HTTP. Most people mean the latter but it's possible to make something meet the key features of REST without using HTTP at all.

It's possible this API meets the standards of the abstract REST concepts. You need a concept of a resource and a standard set of verbs etc. I don't really have time to evaluate the entire API. It does not meet the definition of HTTP-REST that is commonly used.

For HTTP-REST, there are a few things here to clarify. Looking self-explanatory and/or 'natural' is not part of making something RESTful. There are reasons to do it but it's somewhat orthogonal. There are more than 4 verbs in standard REST approaches. GET, PUT, POST, HEAD, DELETE, PATCH, are all ones that are considered somewhat standard. This doesn't appear to be followed at all. I'm not seeing anywhere that it says what method to use. Is it all GET? If so, that's not great security practice, RESTful or not but it may be somewhat mitigated by the authentication requirement.

Answer 2

Should this be considered a RESTful API?

The most common litmus test for whether something is a REST API:

if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API (Fielding, 2008)

There's a decent example of a REST API here: https://api.stackexchange.com/docs/downvote-answer

Fetch the latest version of the form, fill in the details, submit the form, and voila. The client doesn't need to know in advance where the form is going to be pointing, or what method the form is going to specify, because the server is going to provide that information as part of the hypertext representation of the form.

Remember, HTML only provided us with GET and POST, yet it is the Ur example of a REST API.

The spelling of identifiers absolutely doesn't matter.

Answer 3

The term "RESTful" is colloquial used to differentiate an API with different URLs from an API with a single entry point like SOAP. Although a proper definition of REST involves more than using HTTP methods to differentiate API capabilities.

There are some other terms like "RESTlike" or "JSON API" to describe APIs which only implement parts of the REST API definition.

Is something like answers/{id}/downvote considered RESTful?

Just having verbs in the URL is no argument against an API being RESTful. It may be an indicator that the API is not well designed, but it is allowed.

For thinking in resources a better design might be something like PUT answers/{id}/votes/ and returning the putted vote entity updated with a new ID. For answers/{id}/downvote/undo a HTTP-Method could be like DELETE answers/{id}/votes/{id}/. But there might be good reasons not to implement it in this way!

Why not to implement a proper RESTful API?

Although the HTTP standard is very old, one might believe, HTTP is a well implemented protocol. But in reality you will find questionable firewall and proxy technology and security advices to disable parts of the HTTP protocol.

Considering this, it might be a good idea to have at least alternatives in the API, which allow to access all functions with GET and POST requests.

In my humble opinion, be more tolerant on APIs called RESTful. The developers might have good knowledge and best intentions for a REST API, but dealing with the environments of customers might create some weird quirks.