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