Yes, REST advocates say your URLs should be for "resources" not "methods", but sometimes the distinction is blurry. For example, a Google search: http://www.google.com/search?q=restful
Is www.google.com/search a "resource" or a "method"? I would call it a method, but it's also sort of a resource. I can't think of any way to make it more "resource oriented".
You can look at it either way, but it's a perfectly fine resource.
I think, perhaps, it's hard for people to be told they don't get REST when they thought they did but were actually doing a REST-RPC hybrid.
REST advocates have been repeatedly been accused of being religious, but I'm citing reasons you are just saying "and often RPC is the right way to approach an API (better than pure REST)". Which gives meaning to rightness at all.
The "religion" in this debate has nothing to do with any style of architecture, it's simply the rigour people choose to put in to their arguments.
I won't support a bad argument for REST any more than I'll support a bad one for anything else.
However, I don't agree with you on this point, and I'm happy to leave it there. Luckily, I get to work with people like Mark Nottingham, and I'm confident in my points regarding caching.
Doing it RESTfully doesn't loose you anything regarding caching and suddenly you are able to address everything. Personally, I think that's pretty cool.
If people are arguing that, then they don't grok REST (or HTTP verbs, for that matter).
But tell me, why would it be better to POST to /addcomment than to POST to /comments ?
Edit: Or is your point just that some people misapply REST? There's nothing surprising about that.
Just my two cents, but I'm not a fan of a POST with /add. POST already says create. PUT says update. /add is wasteful and confusing when you already grok HTTP verbs.
If you don't really think in terms of HTTP verbs though, then /add reduces confusion. The more uptake REST gets, the more natural it'll seem.
Er, paul actually said PUT to the document (with no particular URI given). POSTing to /comments vs. /addcomment is pretty much a moot point, but I think I agree that "PUT to the document" to add a comment is the wrong thing to do. PUT implies overwriting and should be idempotent. It seems to make sense for _editing_ comments, but the only way I could think of to create a comment that way is to have the client PUT the comment with a GUID. Which seems rather icky: do you want GUIDs messing up your pretty URI space with strings of junk?
Posting to the container therefore makes sense as it's equivalent to a factory method to make a child of the container.
I think a comment on Damien's blog summed it up nicely:
"I love living in the modern age.
It's so refreshing to have moved from religious fights based on the Bible to religious fights based on RFCs."
Most of what he describes in this post is fairly reasonable, but his previous REST post (that I mentioned as silly) focused on the less reasonable (and more dogmatic) parts. He criticized APIs for such things as, "REST API Sin #1: URIs Identify Methods Instead of Resources (The Original Sin)". Referring to design decisions as "sins" may be cute, but it's also a clue that you may be drifting away from pragmatism and towards religion.