This is not so much specific to REST (although very common), it is more in the realm of TBL's "Cool URIs don't change" about URI design [1].
Even though the actual call to the REST service is opaque there is always a person that creates the calling application. Design an API that you would like/enjoy developing against.
What a strawman. Just because URI layout is orthogonal to REST does not make it a non-concern to REST proponents. It has nothing to do with REST. It is a good practice. Both are true.
It's only confusing if you think REST nebulously means merely "good web API design" or "good usage of HTTP."
All this is nice and well, but how would one build an "unsubscribe" link into a newsletter system without a GET request changing the state of the resource (i.e. deleting the email address from the active recipients table by just clicking a link)?
Would this be the exception to the rule or is this problem totally unrelated to REST?
These are guidelines and not unbreakable rules. I think it's fine to have unsubscribe link change the state of the resource. [And personally, I would only flag the user for not sending emails, not delete his email altogether.]
It depends on where the link is. If it's in a web page and the user's browser supported any valid method in forms, you could use a form with method="DELETE" and action="uri for user's subscription", with a submit button styled to look like a link. For browsers that don't support the DELETE method in forms, you can add a hidden input _method=DELETE which is the semi-standard workaround for incomplete browser support. (Your service has to look for _method when it gets a POST and react accordingly.)
If the link is in an email, a form probably won't work. Email clients are still worse than browsers when it comes to styling buttons to look like links. In that case, you can use a real link, but add the _method=DELETE to the url parameters. You service can then look for _method on GET requests too. But it's bad and hacky to change a GET into a DELETE, so you really should just use the link to display a web page, then delete with a DELETE or POST from there. That's what most unsubscribe links in emails do anyway.
In my opinion, you should not initiate a removal from an email. In part due to this. Instead you give the recipient a link to a web page where you have a form that sends either a POST or DELETE to the application.
"Should not" used in the rfc2119 definition. There are always exceptions.
"Don't use query parameters to alter state"
"Don't fall into RPC with your URIs"
I can see the benefit of doing some of the things on the list, but I never understood what's the motivation behind these two suggestions. What are the practical benefits? (Specifically, what are the benefits for a web application, rather than a web app?)
It enables automatic routing without the need to write explicit, case-by-case routing logic or .htaccess files. It doesn't mess up the base path, so I don't need to do some magic when writing URLs. Moreover, it's straightforward. It's easy to see what's going on on the web pages, in the code and in the logs, because knowing a URL means immediately knowing which controller and action are involved (which is not the case with clever resource-mapping schemes).
I think the most important part is whether you are respecting the semantics of the HTTP methods or not. A GET request should never delete something just because the URL says "method=delete".
> A GET request should never delete something just because the URL says "method=delete".
More generally, a GET must not alter application state. It can change a cache or a logfile (these are either implementation detail or irrelevant), but if there is any way for the user to see what was changed, then it does not belong in a GET[0].
[0] things like consumption quotas management are of course a different matter, but they're meta-data more than application state.
Hmm that could work for an unsubscribe page, since the user is motivated to make the second click. However, for an email with a sign up link or a subscription confirmation link having an extra step could reduce your conversion rate somewhat.
but OTOH semantics of GET allow e-mail servers to implement a link scanner that e.g. checks all linked pages for phishing.
That breaks (and likely is broken already in practice) when pages don't respect semantics of GET and unsubscribe/verify, etc. when page is merely displayed.
There are interesting cases, though, where multi-selecting items and then acting on them could require using a query parameter. "action=remove", "action=update", "action=validate" or something like that.
When dealing with singular resources - it's much easier to follow the HTTP methods and verbs but I'm still at a loss for how to handle multi-select cases where you can't represent 20,30,100+ items as a single resource in the URI.
This, is only in the case of a user's UI web experience and not an API - because I haven't figured this part out yet, I haven't supported batched actions like this in the API (haven't needed to, but it could be useful?).
I can see the benefits in respecting request method semantics, but you can do that while using query strings, can't you? If someone calls http://example.com/?Bla.delete.1 with GET, you can just return 405 and do nothing.
I think that would technically fit the constraints, but it eliminates some of the benefits of the uniform interface if you have to POST to some URL instead of simply DELETEing the resource.
Again, you can have a URL like http://example.com?Articles.delete.1 and only accept DELETE requests. (However, I'm speaking about web applications, rather than services. This URL would be useless, since browsers don't support form-based DELETE and PUT for some reason. But that's beside the point.)
Point is, proper handling of GET, POST, PUT and DELETE is all about what you do when receiving those requests, not about the way you compose your URLs. At least that what it seems to be. If I'm wrong, I would very much like to hear why.
But you want to DELETE the actual article, not its deletion page ;) More specifically, if the client is reading an article in some URL, he shouldn't need to find out what's the special deletion URL. It leads to more brittle and less generic clients, with more work for the developer.
Point is, proper handling of GET, POST, PUT and DELETE is all about what you do when receiving those requests, not about the way you compose your URLs. At least that what it seems to be. If I'm wrong, I would very much like to hear why.
I think you're right if the goal is to abide by the REST constraints.
I see what you're saying about deleting the deletion page. It's an interesting point. Having separate URLs for GET, POST, PUT, DELETE, etc. on the same logical entity breaks the connection between those operations. However, I still don't see much added (practical) value in maintaining that connection, especially when it comes to websites (vs APIs). Even in perfect REST world, an article can be represented by a dozen URLs:
They might look different and only some of them might be DELETEable. (Or am I wrong here? I'm not entirely sure.) How that's different from treating http://example.com?Articles.delete.1 as a deletable representation of the same article? Both will affect many other pages on the website. You still need to understand what the request means to really know the consequences of sending it.
In short, I don't think there is anything particularly wrong with doing URLs the way I described.
Well, there is also something as "state". You don't want "method=delete" to work as POST either, unless the client is authorized. Same with GET. I don't see why POST would be better than GET really.
In practice, this is a non-issue. Instead of thinking of your routers as "the interface" and your controllers as "implementation" you can think of the controllers as the interface and everything else as "implementation". If you're concerned about arbitrarily changing class and methods names that are only used as interaction points for the user, you should be similarly concerned about arbitrarily changing routing logic.
In this same vein, I am curious what you guys think of using semi-colon and comma characters in URLs when pointing at an endpoint that generates a response that would typically be provided by a query string, e.g.:
RESTful Web Services Cookbook[1] gave me the idea (a fantastic book) and what I like about it, is that interstitial proxy software seems to molest the URL less where as some refuse to pass through query string params for some reason (e.g. CloudFront).
My first thought was "maybe we should back up and emphasize that resources are nouns before going further", but if you scroll up you'll see that this was actually the original question asked (how do I avoid naming them with verbs?).
I quote it, because it resonates with a lot of people. Especially those who abhor the factoryfactories. Why are the nouns undisputed when it comes to REST? It might map to the web, but does it map well to computing?
Glad to see that - I'm seriously puzzled by the number of references I see to "RESTful URIs".