If your API could benefit from a particular verb (SEARCH, MOVE, CHECKOUT), just use it. You don't need (more) permission from (another) RFC - RFC 2616 and 7231 [1] already gave you permission to add verbs.
Most libraries and tools support arbitrary verbs including `XMLHttpRequest` and `curl`. Yes, there are a few libraries and frameworks that don't easily support arbitrary verbs, but the ones that have added support for PATCH generally have opened up.
Look, there are two Internets. One for people and one for machines. Our RESTful APIs are intended for consumption by machines, not people. You don't have to wedge everything into GET and POST and abuse query parameters to convey what you really mean.
- Routes that intended for use by people via clickable links (web browsers and email clients) obviously must use GET; I believe HTML forms are likewise limited to GET and POST by the `method` attribute (I've never submitted a PATCH form myself).
- You may have to interop with intermediate proxies that perform some form of DPI. For example, some proxies know that certain requests can be cached based on a URI. These proxies may not have support for custom verbs.
- Corporate firewalls may whitelist verbs [1].
In general, the idea is to strive to use verbs that have broad applicability in your API, but that doesn't mean every resource must implement every verb (e.g. read-only collections usually don't implement DELETE). But that's just an standard application of the uniform access principle.
[1] http://www.hanselman.com/blog/HTTPPUTOrDELETENotAllowedUseXH...
A framework that doesn't support extensible verbs in 2014 is bound to have more problems than just a failure to implement one RFC correctly.
Precisely, in a way.
Keep things sane and stick to GET/POST/PUT/DELETE.
You can't win. Do what is right, and then scale back to what the circumstances allow.
EDIT: If we consider adding methods to HTTP, it is easy to imagine a new method, named say CALL or RUN, which would allow arbitrary procedures to be run bound to the requested resource, allowing for a sort of "object-oriented" RPC over REST...
If anyone has anything on implementing more complex REST APIs, I'd be interested in reading it.
GET /product/recommended?user_id={user_id}
the "type" of products you want is a sub-set of all products (recommended). For differentiators I think using params is good. You can then do something like:
GET /product/recommended?user_id={user_id}&rating=5
etc...
Seems clean to me, but also is just my opinion.
To really do it, you'd want /emails instead of /email, and then you'd expect that you could access any given email by /emails/<id>, getting a 401 or 403 if you tried to access one that doesn't exist. Further, you could expect that you could then augment the email resource with a status flag, and then you could even sort for sent emails by /emails?status=sent_and_acknowleged or similar.
For your second case, a POST would be a little weird, unless it returned you a new stats_report. I'd suggest changing that to /stats_reports, and have it create a new stats_report object. To view latest, you'd GET /stats_reports/head or something.
Well, yeah, it's what everyone says, but not so easy to do in practice. Especially in complex apps there's a lot of stuff that isn't actually creating, updating or deleting an object, it is semantically an action. Say, action "send email" (and not some random email, but related or even defined by some business object you are referring to). Or in bookkeeping apps you often need something like "recalculate", which you probably wouldn't like to think of as "updating" because it isn't "take these values and apply to that object", but rather "hey, it's time to make some decision: please run some process (probably, with side effects) and tell us what the result is". Or it might be an action like "moveToQueue<Name>". Or better yet, you explicitly are telling your system to make some interaction with third-party service which is essentially imperative (like GDS, or some external trading API or whatever that isn't an object for your system, but really more like a service for which your app is just a friendly gateway). It is a little bit hard to think of good example right away, because if there is action "purchaseTicket" and there's no object "ticket" in your system you might ask WHY there's no object ticket in your system, but in all specific enough systems there always are situations like this, and mostly for some good reason. And yeah, there's also decisions made for performance sake or simplicity of client-app (like some frontend-side "action queue" so that you can use reactive programming on front-end in more natural way).
So what do I do then? All URLs like "/user/123/order[s]"(PUT,GET,...), "/product/321/comment[s]"(PUT,GET,...) and, suddenly "/sale/copyToAnotherService"? Now that kind of inconsistency is something I really don't like.
…And while I was writing the last one I though about: how should look url for something like "getRecommendedProducts" which depends on both user and product?
Now writing nouns/action names is a bit messy and so not-RESTful, but you always are able to write exactly what you mean by that request.