Which HTTP verb should I use to trigger an action in a REST web service?

Question

I am implementing a RESTful web service and one of the available actions will be reload. It will be used to reload configurations, cache, etc.

We started with a simple GET to an URI like this: ${path}/cache/reload (no parameters are passed, only the URI is called). I am aware that data should not be modified with a GET request.

Which is the correct verb to use to invoke an action/command in a RESTful web service?

The reload is a command of the REST web service that reload its own cache/configuration/etc. It is not a method that returns information to the client.

Probably what I am trying to do isn't REST, but it is still something that need to be done this way. The reload method was only a real example that makes sense in the scope of the application and most answers focused on it, but in fact, I just needed to know which verb to trigger an action that doesn't do CRUD, but still changes data/state.

I found this detailed asnwer on Stack Overflow abot the subject: https://stackoverflow.com/questions/16877968/

Answer 1

I don't think there is a proper verb for this action because this transaction isn't really "RESTful." The "s" and "t" stand for "state transfer" and nothing is being transferred here. Or, put another way, by the strictest definition, the verbs like PUT and POST are always used with a noun and "reload" just has the verb.

This reload may not be RESTful, but it may still be useful and you'll just have pick a way to do it and live with or explain that it's unusual. GET is probably the simplest. There's a fair amount of skepticism in the comments, though, so you should think about whether or not this reload action is required because something else isn't quite doing what it should be doing.

Answer 2

If you want to be RESTful don't think of the verb to carry out an action, think of the state you want the resource to be in after the client has done something.

So using one of your examples above you have an email queue that is sending emails. You want the client to put that email queue into the state of paused or stopped or something.

So the client PUTs a new state to the server for that resource. It can be as simple as this JSON

PUT http://myserver.com/services/email_service HTTP/1.1
Content-Type: text/json

{"status":"paused"}

The server figures out how to get from the current status (say "running") to "paused" status/state.

If the client does a GET on the resource it should return the state it is currently in (say "paused").

The reason to do it this way, and why REST can be so powerful, is that you leave the HOW to get to that state up the server.

The client just says "This is the state you should be in now" and the server figures out how to achieve that. It might be a simple flip in a database. It might require thousands of actions. The client doesn't care, and doesn't have to know.

So you can completely rewrite/redesign how the server does that and the client doesn't care. The client only needs to be aware of the different states (and their representations) of a resource, not any of the internals.

Answer 3

Some of the other answers, including the accepted one, advise you to use a GET (though not very enthusiastically).

I disagree.

First of all, all the others telling you that this is not ideal and not really RESTful are correct. In a proper RESTful scenario, you are manipulating resources on the server and adding, updating, deleting, retrieving, etc those resources. A PUT should send a payload that represents what the resource should be when the request is complete, and POST should send a payload that represents a resource to be added to the server. And a GET should return a resource on the server.

You have an RPC (remote procedure call), which isn't RESTful - you want to DO something on the server. So if you're trying to create a purely RESTful API, you should reconsider what you're doing.

That said, sometimes you do need to bend the rules a bit. Especially if you're developing an internal api that isn't going to be exposed to the public, you may decide that the trade-off is worth it.

If you do, I would recommend a PUT or POST, depending on whether or not the RPC is idempotent or not.

In general, we say that HTTP PUT maps to SQL UPDATE and that HTTP POST maps to SQL INSERT, but that's not strictly true. A purer way to state that is that HTTP PUT should be idempotent and HTTP POST needn't be. This means that you can call the same PUT request as many times as you want with no side-effects. Once you've called it once it's harmless to call it again. But you should not repeatedly call POST requests unless you mean to - each POST changes data on the server again.

In your case, if you need to have this reload function, I'd recommend a PUT because it sounds like it's idempotent. But I would still urge you to consider what the others said about not needing it at all.

Answer 4

POST and PUT are the HTTP verbs used to submit an entity to a web server. With PUT, the submitted entity is the (new) representation for the resource at the given URI, which doesn't fit what you want. POST is for the traditional form-handler, where the entity is ancillary data for the resource, so that's the winner. The entity would include the command or action (e.g. "action=reload").

That said, the command in question probably shouldn't be exposed via a REST interface. It sounds like the necessity for "reload" arises because data can be changed via some other channel (e.g. filesystem, DB client). Caches should be transparent. Moreover, HTTP requests should be atomic, even taking messages sent over other channels into consideration. Offering a "reload" command for configuration settings seems an unnecessary complexity; requiring it is a brittle design. Exposing "reload" to clean-up after an update via another channel is dirty because one channel doesn't contain the entire conversation. Instead, consider one of:

• making updates entirely via REST
• exposing the command(s) to the other channel
• automating the actions

Some of those options might not be viable, depending on what other restrictions exist.

See also "PUT vs POST in REST".

Answer 5

Why not treat the action like a resource. So since you want to update the cache, you would POST a new action in your system.

For purists, you could have a dedicated urls for that. Note that you could extend this and log the actual actions in a database (or whatever storage) with date, status, user, etc... Just my thoughts here.

Generic system-wide operation /actions/{action}

Operation specific to a resource type /actions/{resource}/{action}

Operation specific to a resource /actions/{resource}/{id}/{action}

In your case, the cache is probably system-wide /actions/reload_cache

Answer 6

When facing a similar scenario to the one you described - wanting to use a verb as part of a REST endpoint - I typically solve it by transforming that verb into a noun.

So instead of:

GET ${path}/cache/reload

I'd do a:

POST ${path}/cache/reload-request

This will force a shift in how you think about your action. You should now think about how to create a new resource that represents the reload request. Since HTTP requests are normally short-lived this creates a nice abstraction that allows you to return a resource containing id and status and send the actual action to be processed in the background. Then the caller can check later if the request has been processed by doing:

GET ${path}/cache/reload-request/{id}

Or even cancel the request by doing:

DEL ${path}/cache/reload-request/{id}

Sometimes your action is so quick and simple that just returning 200 OK with an empty body is enough. That tells the caller you've taken the request to execute the action and processed it already, without the need for further calls to check the status.

Answer 7

I would argue why a client request would explicitly need to make a call to refresh something like that. It sounds like that should either be hidden logic on a more typical implementation of GET (I.e. Pull data, but the service makes a refresh on the data before it is pulled), or by another trigger in the backend away from the client.

After all, the data/config would only need to be current on subsequent calls, so I would lean more towards a lazy vs eager call for a data refresh. Obviously I am assuming a lot here, but I would take a step back to reevaluate the necessity of such an explicit and standalone call.

Answer 8

Which HTTP verb should I use to trigger an action in a REST web service?

When considering the details of a REST service, it is often useful to consider this heuristic: how would you implement this with a web site?

HTML can only natively describe GET and POST requests. So we can start are search there.

Is GET appropriate? To answer this question, we need to think about the assumptions that clients and intermediate components are allowed to make about GET. The semantics of GET are safe

the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe method is not expected to cause any harm, loss of property, or unusual burden on the origin server.

The implication, therefore, is that the clients and intermediate components have discretion to invoke a GET request as frequently as necessary to satisfy their own concerns. Spiders can GET resources indiscriminately to update their indexes. Caches can pre-fetch. On an unreliable network, lost messages can be retried as frequently as necessary to ensure at-least-one response.

It will be used to reload configurations, cache, etc.

If these are expensive things to do, then maybe you don't want the clients to issue these requests at their own discretion.

POST, on the other hand, is effectively unconstrained -- this greatly reduces the assumptions that generic clients are allowed to make. You don't get components making speculative POST requests because they would be faulty to do so -- nothing in the standard says that's OK.

PUT, PATCH, DELETE... these are unsafe methods with more specific semantics than POST; whether or not they are appropriate is going to depend on your resource model.

An important idea to keep in mind is that the HTTP methods belong in the document domain (See Jim Webber's 2011 talk), the effects you are describing are probably not part of the document domain, but are instead side effects invoked when the documents are changed. That gives you a lot of freedom in terms of how you organize your documents to get work done.

Answer 9

What about PATCH?

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH

A PATCH request is considered a set of instructions on how to modify a resource. Contrast this with PUT; which is a complete representation of a resource.

A PATCH is not necessarily idempotent, although it can be. Contrast this with PUT; which is always idempotent. The word "idempotent" means that any number of repeated, identical requests will leave the resource in the same state.