General principles for good URI design for RESTful and HTTP applications | Hacker News Reader

General principles for good URI design for RESTful and HTTP applications

stackoverflow.com

97 pointsibrahimcesar38 comments

Open articleView on HN

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

> Glad to see that

Exactly my thoughts, the submission title had me prepare a facepalm, but the linked comment is very good.

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?

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

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

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

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

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

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.

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

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

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.

http://www.ietf.org/rfc/rfc2119.txt

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

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

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

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

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

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.

What about from an email?

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

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.

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.

Again, you can have a URL like http://example.com?Articles.delete.1 and only accept DELETE requests.*

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.

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:

http://example.com/articles/3423423 http://example.com/reviews/fallout-new-vegas http://example.com/bob/submissions/articles/13

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.

Theoretical reason: because that's what the HTTP spec says.

Practical reason: because browsers have prefetching systems that might GET resources without asking the user, which might be authorized anyway.

That's all fine and dandy until you change a class name, method name, parameter name.

Way to expose internal details about your implementation, though.

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.

So instead of having a router and controllers, you're just making the controllers do the work of the routers too.

I mean, you can, but why would you?

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

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

Which reminds me: 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?

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

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.

Reply on news.ycombinator.com