12 ms·

General principles for good URI design for RESTful and HTTP applications

97 points by ibrahimcesar 15y ago

arethuza 15y ago
"(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".
- masklinn 15y ago
  > Glad to see that Exactly my thoughts, the submission title had me prepare a facepalm, but the linked comment is very good.
- tantalor 15y ago
  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?
  - icebraining 15y ago
    Worse and better are subjective; but neither version impacts on whether the system is REST or not, since they don't break any of the constraints, are defined by Fielding: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...
  - njharman 15y ago
    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 15y ago
      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."
    - wahnfrieden 15y ago
      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."
  - eCa 15y ago
    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. [1] http://www.w3.org/Provider/Style/URI.html http://www.w3.org/Provider/Style/URI.html
  - masklinn 15y ago
    > If that is true, why do so many guides stress URI design? Because these guides are written for people who don't understand what they're talking about? > Would anybody balk if all my REST API's URIs where obscure hashes? > Is this no worse or better? In terms of "RESTfulness" there is no difference whatsoever. In terms of clarity, readability and debuggability, the former is better.
romaniv 15y ago
"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 15y ago
  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".
  - Ixiaus 15y ago
    This is a good example of what was meant, IMHO. 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?).
  - masklinn 15y ago
    > 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.
pooriaazimi 15y ago
This article on how to design a RESTful API is really great: http://www.ibm.com/developerworks/webservices/library/ws-restful/ http://www.ibm.com/developerworks/webservices/library/ws-res...
decklin 15y ago
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 15y ago
  Which reminds me: http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom... 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?
moozeek 15y ago
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 15y ago
  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 15y ago
    > [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...
- DougWebb 15y ago
  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.
- eCa 15y ago
peterwwillis 15y ago
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.
rkalla 15y ago
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-Scalability/dp/0596801688/ref=sr_1_1?ie=UTF8&qid=1328307149&sr=8-1 http://www.amazon.com/RESTful-Web-Services-Cookbook-Scalabil...

97 points by ibrahimcesar 15y ago

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

masklinn 15y ago
> Glad to see that Exactly my thoughts, the submission title had me prepare a facepalm, but the linked comment is very good.
tantalor 15y ago
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?
- icebraining 15y ago
  Worse and better are subjective; but neither version impacts on whether the system is REST or not, since they don't break any of the constraints, are defined by Fielding: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...
- njharman 15y ago
  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 15y ago
    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."
  - wahnfrieden 15y ago
    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."
- eCa 15y ago
  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. [1] http://www.w3.org/Provider/Style/URI.html http://www.w3.org/Provider/Style/URI.html
- masklinn 15y ago
  > If that is true, why do so many guides stress URI design? Because these guides are written for people who don't understand what they're talking about? > Would anybody balk if all my REST API's URIs where obscure hashes? > Is this no worse or better? In terms of "RESTfulness" there is no difference whatsoever. In terms of clarity, readability and debuggability, the former is better.

romaniv 15y ago

"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 15y ago
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".
- Ixiaus 15y ago
  This is a good example of what was meant, IMHO. 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?).
- masklinn 15y ago
  > 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.

pooriaazimi 15y ago

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

decklin 15y ago

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 15y ago
Which reminds me: http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom... 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?

moozeek 15y ago

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 15y ago
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 15y ago
  > [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...
DougWebb 15y ago
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.
eCa 15y ago

peterwwillis 15y ago

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.

rkalla 15y ago

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-Scalability/dp/0596801688/ref=sr_1_1?ie=UTF8&qid=1328307149&sr=8-1 http://www.amazon.com/RESTful-Web-Services-Cookbook-Scalabil...