Generally speaking, RESTful API's are very good for representing resources and collections of resources. http://example.com/resourceshttp://example.com/resources/item17And 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 subresourcePOST http://example.com/resource/item17/sendemailOn one hand, it's straightforward. On other hand, it start smelling SOAPy (read RPC calls).Represent an action as a standalone resourcePOST http://example.com/emailsenderThis 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?
How to provide a service with RESTful API?
design;rest
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/SomeCoolDudehttp://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.)