2

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" }?

  • What difference does it make if they are or not? – whatsisname Feb 15 at 20:27
  • @whatsisname There are tons of articles explaining REST design principles, tons of libraries offering REST capabilities, tons of jobs asking for knowledge of REST. I guess that it's quite relevant ,today, for a software engineer, to know what REST is (and what it isn't). Discussing concrete examples help (me at least) to learn. – leonbloy Feb 15 at 21:22
  • Do you know what does REST means?. – Laiv Feb 15 at 22:29
  • Think of them as nouns “a downvote”, “a delete(ion)” and “an undo”. They could be resources in that domain that need separate HTTP verbs and that’s perfectly reasonable. If not, then it’s just “impure REST” i.e., And endpoint design leveraging HTTP verbs for design. – PhD Feb 17 at 17:23
2

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.

  • Thanks. I'm not interested in judging the entire API, but on that particular issue with verbs in URLs – leonbloy Feb 14 at 22:00
  • 1
    @leonbloy: ReST doesn't care what your URIs look like. Quite the opposite: the moment you start caring what your URIs look like, you are not doing ReST! HATEOAS means that your client makes progress by following links given by the server. Since the link is handed to you, and you don't need to look at the link, only send it back to the server to tell it you want to follow that link, it is fundamentally irrelevant what the link looks like. Note: there are other reasons, you might care about what the URIs look like, readability, and SEO for example. But ReST has nothing to do with it. – Jörg W Mittag Feb 14 at 22:24
  • @JörgWMittag So you disagree with the answers I linked, and with this (598 upvotes) answer stackoverflow.com/questions/2001773/… ? – leonbloy Feb 14 at 22:38
  • 2
    @leonbloy: I don't have time to go through all of those. If those links indeed say that URIs should look a certain way "because ReST says so", then yes, I disagree, since they are what we in the industry call wrong. If they say that URIs should look a certain way for some other reason, then they are probably right, since there are a myriad of reasons why URIs should look a certain way. It's just that ReST is not one of them. For example, the Apigee post you linked uses constraints on what a URI is allowed to contain as guiderails towards a good ReST design. That is perfectly legitimate. – Jörg W Mittag Feb 14 at 23:42
  • 1
    @JörgWMittag the quoted answer does say something about how URI's should look like and I guess you are concerned with the explicit name while leonbloy is concerned about the rough semantics. I.e. the suggested 'downvote' endpoint would exactly match the "bad example" (activate_login) from that answer in that it's not a standard ressource operation. – Frank Hopkins Feb 15 at 0:12
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.

  • The example you point to doesn't exhibit what your Fielding link says is required. Most obviously it violates this: "A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server)." It's not clear how this is an example of using hypertext as he defines it: "simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions." – JimmyJames Feb 15 at 17:51
  • Is there not a big HTML form at the bottom of the page when you look at that link? – VoiceOfUnreason Feb 15 at 19:32
  • That isn't the way Fielding defined hypertext in the link you post. He specifically states in a comment: "Hypertext does not need to be HTML on a browser." It's in response 3 where he defines hypertext: text plus links. The SE API doesn't meet the definition given in the content of the blog. Specifically by not "defining those instructions within media types and link relations" but with 'out-of-band' information (fixed URI structures defined in the docs.) His claim is that to use the API you should need no knowledge other than the "initial URI" and "standardized media types". – JimmyJames Feb 15 at 21:11
1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.