REST services - exposing non-data “actions”

Question

I understand how to use REST for doing general entity interactions - using urls names to map to entities and the HTTP verbs to map to actions on those entities. But what is the generally accepted way of looking at "actions" more like RPC?

For example, let's say I want to send a command for the device to reset? There's no real "entity" here or do I do something like POST to http://mydevice/device/reset?

Answer 1

/device/reset or /system/reset are ok.

The REST "design pattern" does encourage you to NOT use any verbs.. You could do:

POST http://mydevice/system/state    
<stateType>RESET</stateType>

Related information:

• How to create REST URL’s without verbs?
• Threads tagged with restful-url

Answer 2

I don't think that's the case to use POST. The "RESET action" is a idempotent action (if you call it n times you will always get the same result), so IMHO you should use a PUT call instead POST (as POST is not idempotent).

Also, as you are Putting a resource, you can use

PUT http://system
<device>
  <status>RESET</status>
</device>

or

 PUT http://system/status/reset

But I think the first one is "more restful", since you are putting a resource, while the second one you just use the URL.

Answer 3

I usually name the entity "system" or something like that. So you do "/system/reset". You've chosen device so that works too.

But yea, I usually consider these types of actions to be updates, which would use the POST method. So I think you are right to POST to /device/reset