Triggering an action POST or PUT

Question

I've read PUT vs. POST in REST in full and also w3 docs but still not sure of what's the right approach.

If I want to turn on the heater:

POST /house/123/

{"appliance" : "heater" , "action" : "on"}

or

PUT /house/123/

{"appliance" : "heater" , "action" : "on"}

or I should be using some other method? I think neither of them solve the question at hand since there is no object creation happening here...

EDIT:

What if I it's just just turning on/off. Rather it's a reboot. Think of it as something that needs to happen. Doesn't necessarily need to be a change of state.

/house/123/

{"action" : "reboot-heater"}

Note that it's an IETF document, not a W3 document, and that the version you're looking at is very outdated. — Julian Reschke, Nov 27 '18 at 05:16
It is not a W3 document, so there's no update there. The current HTTP/1.1 are RFCs 7230..5. — Julian Reschke, Nov 28 '18 at 05:18
I'm not really good at this. Do you mean [this](https://tools.ietf.org/html/rfc7230). I don't see anything about PUT. Can you share the latest link that addresses definitions — mfaani, Nov 28 '18 at 12:12

score 3 · Accepted Answer · answered Nov 26 '18 at 18:12

Both methods are appropriate, in various circumstances.

POST is the universal method - you can use it for anything, although there are often better choices (ex: GET, when the operation is safe). HTML only supports GET and POST, and it is the lingua franca of the web. So you can infer that POST is fine.

PUT also works; it's analogous to "save", "replace", "upsert". The issue with PUT is that the semantics are that the request payload is a replacement for the current state of the target resource.

In effect, that means that

PUT /house/123/

{"appliance" : "heater" , "action" : "on"}

should be a complete replacement for the state of /house/123. That's probably not what you want, assuming the state of the house includes descriptions of other appliances, rooms, occupants, location, and so on.

You could PATCH the house, describing the change to the heater with a patch document. But that relaxes the idempotent semantics that are an important benefit of PUT.

You could also PUT to a different target resource - but that may not give you suitable caching behavior.

It's important, if you want to get the framing right in your head, to think about the fact that the resources are part of your integration domain. Your REST api is a disguise that your server wears, pretending to be a dumb HTTP key value store.

A good read, if you have time, is RESTful Casuistry, where a bunch of folks discuss what a RESTful protocol for requesting a server shutdown should be.

Triggering an action POST or PUT

1 Answers1