Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Is using a verb in URL fundamentally incompatible with REST?

Tags:

rest

So let's say we have something that does not seem best represented as a resource (status of process that we want to pause, stateless calculation we want to perform on the server, etc).

If in API design we use either process/123/pause or calculations/fibonacci -- is that fundamentally incompatible with REST? So far from what I read it does not seem to, as long as these URLs are discoverable using HATEOAS and media types are standardized.

Or should I prefer to put action in the message as answered here?

Note 1:
I do understand that it is possible to rephrase some of my examples in terms of nouns. However I feel that for specific cases nouns do not work as well as verbs do. So I am trying to understand if having those verbs would be immediately unRESTful. And if it is, then why the recommendation is so strict and what benefits I may miss by not following it in those cases.

Note 2:
Answer "REST does not have any constraints on that" would be a valid answer (which would mean that this approach is RESTful). Answers "it depends on who you ask" or "it is a best practice" is not really answering the question. The question assumes concept of REST exist as a well-defined common term two people can use to refer to the same set of constraints. If the assumption itself is incorrect and formal discussion of REST is meaningless, please do say so.

like image 352
Andrey Shchekin Avatar asked Oct 28 '13 23:10

Andrey Shchekin


People also ask

Can you use verbs in REST API?

Simply because RESTful APIs are based on resources and use the HTTP verbs (GET, POST, PUT, DELETE, PATCH), does not mean they should only support CRUD (Create, Read, Update, Delete) operations. RESTful APIs can also be used for performing other actions on resources.

Should HTTP verbs be used in Uris?

HTTP verbs are preferred if possible, as they are part of the HTTP protocol and as such a standard. It also allows you to use existing security and caching layers on a standard web server, without having to write any bespoke middleware.

Which kind of word should be used in the URL of a REST API to access a specific resource?

Use nouns to represent resources. RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties that verbs do not have – similarly, resources have attributes.


1 Answers

This article has some nice tips: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Quoting from the article:

What about actions that don't fit into the world of CRUD operations?

This is where things can get fuzzy. There are a number of approaches:

  1. Restructure the action to appear like a field of a resource. This works if the action doesn't take parameters. For example an activate action could be mapped to a boolean activated field and updated via a PATCH to the resource.

  2. Treat it like a sub-resource with RESTful principles. For example, GitHub's API lets you star a gist with PUT /gists/:id/star and unstar with DELETE /gists/:id/star.

  3. Sometimes you really have no way to map the action to a sensible RESTful structure. For example, a multi-resource search doesn't really make sense to be applied to a specific resource's endpoint. In this case, /search would make the most sense even though it isn't a noun. This is OK - just do what's right from the perspective of the API consumer and make sure it's documented clearly to avoid confusion.

I personally like suggestion #2. If you need to pause something, what are you pausing? If it's a process with a name, then try this:

/process/{processName}/pause 
like image 114
ccleve Avatar answered Sep 18 '22 17:09

ccleve