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?

EDIT: 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.

FINAL EDIT: 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/

  • 1
    "Reloading" is the sense of an app refreshing the data it's going to display? Is there any difference between reloading and just getting the data again? – Sean Redmond Nov 2 '14 at 2:25
  • 1
    @SeanRedmond No, the data is not sent to the client. In fact, is the client saying to the REST web service to execute and internal command (reload). Something like: "a lot of configurations were changed in database, so REST web service, reload them to your memory now". – Renato Dinhani Nov 2 '14 at 2:46
  • Cross-site duplicate: stackoverflow.com/q/15340946/319403 – cHao Nov 2 '14 at 4:58
up vote 21 down vote accepted

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.

  • I agree that this isn't RESTful but may be useful. I think you should advise a PUT though, because this is probably idempotent but not nullimpotent. – Aaron Greenwald Nov 3 '14 at 21:01
  • @Aaron, the comparison of idempotent and nullimpotent is all well and good, but how do you determine when it's notimpotent? – Craig Jul 30 '15 at 20:01
  • @Craig it's idempotent if running it many times has the same effect of running it once. It's nullipotent if running it once or many times has the same effect on the server as running it zero times. en.wikipedia.org/wiki/Idempotence – Aaron Greenwald Aug 1 '15 at 4:21
  • 3
    @AaronGreenwald “notimpotent” [not-im-poht-nt] [not-im-pawr-tnt] - adjective - 1. A play on words, “not important,” antonym of the adjective “important.” 2. Humor… ;-) – Craig Aug 1 '15 at 6:32
  • @Craig I completely missed that :) – Aaron Greenwald Aug 2 '15 at 19:35

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.

  • 1
    As far as I'm concerned this is the correct answer. Refreshing data on the server is not an idempotent operation, and GET is a completely inappropriate verb to use. PUT is the most appropriate verb as the operation can be thought of as updating the "reloaded status" of the cache to "reloaded". – Jez Apr 27 '15 at 15:17
  • @Jez Of the answers here, I prefer this one as well. Sticking with the email metaphor, offhand it does feel odd at first to think of sending the mail by putting it into the "sending" state instead of just sending it (an action). But if you think about it, that's really the same thing as putting it in the "outbox." In fact, the mail system itself is probably queuing it that way internally when you tell it to send. So the API can let you put the mail in the "sending" state, and the API isn't obligated to explain itself beyond that. – Craig Jul 30 '15 at 19:57
  • So by extension, if you don't want the message to go just yet, you put it in the "scheduled" state with a date/time when it should be released. If it isn't complete, you put it (or it is implicitly/by default) in the "draft" state, etc. – Craig Jul 30 '15 at 19:57
  • ...although I think I'd prefer POST to PUT in this case, since PUT is also supposed to be idempotent, but POST is under no such constraint. – Craig Jul 30 '15 at 20:28
  • In the OP context, would be ok to do PUT of {"last_reloaded_on": "2015-01-01T12:00:00Z"} so that it's idempotent?. Failing with 409 Conflict if it's there is a more current update?. – ecerulm Dec 8 '15 at 12:27

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.

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".

  • Thank you. I removed the "internal" of the edit because in fact the "reload" method is intended to be public. I just tried to mean it refers to the web service itself. I think posting the "action" would be a good approach. – Renato Dinhani Nov 2 '14 at 3:40
  • @RenatoDinhaniConceição: even without the "internal", it still smells. It might behoove you to ask a new question about whether the design is a good one. – outis Nov 2 '14 at 5:02

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.

  • Look at my edit. "reload" is not a command that returns data. It refers to the REST web service itself. In general terms, my question refers about triggering actions in a REST web service. Other example can be: email_queue/stop_sending_emails. I am justing giving a command to something using a RESTful interface. – Renato Dinhani Nov 2 '14 at 2:52
  • 5
    I still agree. Invoking SIGHUP on a local process makes sense, since the computer should trust someone logged in locally who has access to that signal. But for a stateless, Internet-accessible protocol? Perhaps the web service should automatically reload as necessary via polling or file monitoring. This call should be completely unnecessary. – user22815 Nov 2 '14 at 3:50
  • 1
    I agree. Things like configuration and caching are meant to be transparent to the client. Maybe you should give us a more concrete description of a situation in which your endpoint would be called. – Benjamin Hodgson Nov 3 '14 at 21:26

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

This is not a textbook use case but if you want to be in theory compatible then use PUT which is supposed to update the data. You have no payload though. A simple GET would not be so bad in this case.

HTTP verbs have nothing to do with REST.

You might ask what would be the conventional VERB to do some action , but still , it has nothing to do with REST.

REST is an architectural style , which is mainly about how components communicate with each other. It defines a set of principles , not a set of Protocols or Verbs.

You could create new Resources with the DELETE verb, while it doesn't make any sense and it isn't conventional , it can still be completely RESTFul , as long as the constraints are fulfilled.

As for you question , it's not the verb, the URL , the message format that determine whether its REST or not , but rather the semantics of the API definition of your service and the underlying protocol. Does the "reload" operation breaks any of the REST constraints? It seems to me like it doesn't , so you can use whatever VERB you want , it won't make your service more or less RESTful.

As for your use case , I'd use the GET verb. Simply because there's no HTTP VERB for such action , and these cases I use the GET verb , just because I use HTTP and I have to use some VERB.

  • 2
    Are you sure REST has nothing to do with HTTP verbs? – Andy Wiesendanger Mar 28 '16 at 14:24

I find all the answers very interesting and insightful. However for the original question there is a clear answer to me, that does not feel awkward: Understand 'reload' not as an action, but as a signal. And a signal is a resource. So in a REST style API it would be POST /reloadSignal.

And posting this signal triggers the appropriate action. From a REST perspective I don't think that it is an issue to not store these signals (if not needed for business reasons).

protected by gnat May 8 at 21:43

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.