3

Generally speaking, RESTful API's are very good for representing resources and collections of resources.

And we are good, if we work with resource.

However, what should be done, when you need to expose API which does an action which doesn't create/update or delete a resource.

Couple of examples:

  • You have an algorithm (as example add two numbers)
  • You have an action which uses external system (as example send an email).

I saw two approaches:

Represent an action as a subresource

POST http://example.com/resource/item17/sendemail

On one hand, it's straightforward. On other hand, it start smelling SOAPy (read RPC calls).

Represent an action as a standalone resource

POST http://example.com/emailsender

This looks more RESTful. However, it doesn't feel right too (only one of CRUD actions is implemented). This resource actually doesn't have a representation.

I am not sure, may be there are other methods which I have missed.

The question is - "Is there a consensus on this subject? What is the preferred way to do it?"

3

Since verbs in REST under HTTP are restricted to the HTTP verbs, everything in the URI should be name a noun. So the common trick is to do what you say -- convert the custom verb (sendemail) to a processor noun (emailsender) instead.

At first that seems like a word trick, but it does have some merit. You can then use the "data processing" provision of the POST verb to post commands to your processor. It opens the door to responses like a 202 Accepted if you want to do asynchronous processing.

One thing to watch out for is namespace collision; the processor noun can collide with your identifier namespace. For example:

http://some/site/users/SomeCoolDude

http://some/site/users/emailprocessor

...now you can't have a user named "emailprocessor" because it collides with the processor noun. That may not be a problem if the IDs are ints or UUIDs, but it's something to bear in mind.

...

(And the strict answer is that all the URIs the client uses should come from hypermedia, so the design of the URI should be opaque to the user anyway.)

  • Yeah, I agree with Rob Y. Basically REST applies the HTTP verbs to all actions, and begs a question to all of us OOAD people. What would we do if we were limited to about 4 or 5 methods per class, and they all had to be the same? The answer seems to be "Hey, I didn't realize I could get by without all these different methods (verbs) if I just broke down the noun (class) nomenclature better in my design!" It seems to be that you can break down these relationships almost ad infinitum, and when you do, POST, GET, DELETE, etc. seem adequate. – Calphool Apr 23 '14 at 18:01
  • Please explain "URIs the client uses should come from hypermedia". – Tulains Córdova Apr 23 '14 at 21:58
  • That gets pretty deep. Most people making "REST" interfaces are really just making JSON over HTTP interfaces, because they're missing a central concern: passing hypermedia that tells a client how to modify the state of the resource. In HTML, think of <img> tags or <form> tags. Those are hypermedia, and contain links. In order to meet the basic criterion for REST ;) a RESTful service must return links that tell the client how to modify the resource, or fetch more data. You can't communicate the links "out of band". Look up HATEOAS for more info; there is a lot of discussion out there. – Rob Apr 23 '14 at 22:48
  • @user61852 I should say, that's the ideal. I've only been on 1 team that actually implemented that. That's why I usually just say "JSON over HTTP" instead of "REST". Maybe "Resource-oriented service". Also, a lot of times, if you take the REST buzzword out of a conversation, the answer becomes clear. – Rob Apr 23 '14 at 22:53
1

There is probably no consensus on solutions for such actions. Hey, from what I've read there's not even consensus on how to implement all required characteristics of a REST API.

For performing different actions then just storing resources the resource based URLS can be used. For example sending mail could be implemented as a POST request of a message resource to the collection of messages of a specific user:

http://example.com/users/me/messages

The software handling this request can do additional work when storing this resource. In the case of email use a status field indicating if it is a draft or not, and if not a draft send the resource to the receivers described in the resource.

For things like a calculation service this may be more difficult.

In general I like to look at it this way: How would I exchange a resource with the HTML mime type over HTTP using a browser as client? That matches the largest RESTful API I know of.

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.