

General principles for good URI design for RESTful and HTTP applications - ibrahimcesar
http://stackoverflow.com/questions/1619152/how-to-create-rest-urls-without-verbs/1619677#1619677

======
arethuza
"(Note: I did not say "RESTful URI design"; URIs are essentially opaque in
REST.)"

Glad to see that - I'm seriously puzzled by the number of references I see to
"RESTful URIs".

~~~
tantalor
If that is true, why do so many guides stress URI design?

The canonical example is the "collection" URI,

    
    
        http://example.com/resources/
    

And the "element" URI,

    
    
        http://example.com/resources/item17
    

Would anybody balk if all my REST API's URIs where obscure hashes?

So my collection is now,

    
    
        http://example.com/b9cbc0a72a17e6b9e271187096c3b981269554fb
    

And the element is,

    
    
        http://example.com/7c2186f626d0aa7dedc0bb7537b578937015ff6e
    

Is this no worse or better?

~~~
njharman
The difference is people who's goal is to follow some pure, academic
definition of REST and people who want to make elegant web services. So,

Pedantic wanks "no worse".

People working in reality "wtf would you ever do that?"

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

------
moozeek
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?

BTW: I'm not debating, I really wanna know.

~~~
solutionyogi
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.]

~~~
moozeek
> [And personally, I would only flag the user for not sending emails, not
> delete his email altogether.]

Sure, just wanted to make my point. In reality you move the subscriber from
"subscribed" to "unsuscribed" or something like this...

------
romaniv
_"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?)

I can give you some _considerable_ benefits of doing the opposite. My favorite
URL scheme looks like this:
"[http://example.com/?Class.method.id.parts&param=x](http://example.com/?Class.method.id.parts&param=x).

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

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

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

~~~
kstenerud
Except, as stated in a different comment, for things such as "unsubscribe"
links.

~~~
masklinn
No, I do not agree.

1\. In a browser, the link would lead to a confirmation page POSTed to the
server

2\. In an API, there's no real sense in doing that, but it'd probably be a
DELETE on the subscription resource.

~~~
kstenerud
What about from an email?

~~~
icebraining
The link takes you to a page with a form where you can confirm by POSTing (to
the user: submitting).

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

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

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

    
    
        http://site.com/generate;lang=en,size=32,weight=78
    

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

Anyone see any glaring issues with this?

[1] [http://www.amazon.com/RESTful-Web-Services-Cookbook-
Scalabil...](http://www.amazon.com/RESTful-Web-Services-Cookbook-
Scalability/dp/0596801688/ref=sr_1_1?ie=UTF8&qid=1328307149&sr=8-1)

------
decklin
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?).

~~~
route66
Which reminds me: [http://steve-yegge.blogspot.com/2006/03/execution-in-
kingdom...](http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-
nouns.html)

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?

------
pooriaazimi
This article on how to design a RESTful API is really great:
[http://www.ibm.com/developerworks/webservices/library/ws-
res...](http://www.ibm.com/developerworks/webservices/library/ws-restful/)

------
peterwwillis
Holy shit, why hasn't this been around forever?

I forgot about 2?? responses other than 200, going to implement that now. Also
going to implement 418 just because it's fun.

