< Dentist 2.0
Next >

[Comments] (4) Human Resources: Scott and I can't comment on each other's weblogs. In the case of my weblog it's because comments are shut down after a week. Anyway, Scott responds to "You're All Resources!":

I guess my struggle with it is that looking at /recent doesn’t make it obvious that’s its recent bookmarks whereas something like /bookmarks/recent or /bookmarks?fromDate=2007-06-01 is more obvious that its a list of bookmarks.

That's a fair point. /bookmarks/recent (or just /bookmarks) would make it more clear to a human what "recent" things exactly are at the other end of the URI. I never considered that because Rails doesn't encourage that kind of thinking, but it's a better URI choice. But we're now in a side issue because what a URI looks like has no formal bearing on what resource it identifies. The URI could be /4350/9885677.4169 and it would still be a resource that gives you recent bookmarks when you GET it.

This is probably not something you were wondering, but I'll address it briefly: how do you make it clear to a computer that there's a list of recent bookmarks at the other end of the URI? There are a number of ways. At one end of the spectrum you can hard-code this information into every client. At the other end you can do some magic Semantic Web thing where terms like "bookmark" and "recent" are given meaning within some ontology that a general client understands. In between you have clients that are programmed to understand certain media types or microformats, and clients that are programmed to understand certain hypermedia formats that contain semantic cues.

In none of these cases does the computer "understand" the resource the way a human does. The goal is to reduce the space between the human's desire "I want to do x to recent bookmarks" and the HTTP request the client ends up making. One one end of the spectrum, the user has to hard-code their desire into the client. On the other, the client can take "x", "recent", and "bookmarks", plug them into the ontology, and figure out which request to make.

Filed under:

Comments:

Posted by Scott Battaglia at Tue Aug 28 2007 10:25

Ah I see! Being a human who may at one point have to program against my resource API, I had assumed that the actual naming scheme is important. I.e. /bookmarks/recent vs. /4350/9885677.4169 (obviously, as you point out it has no formal bearing though)

I would hope that most RESTful developers adopt the former naming scheme rather than the latter. Though a machine may be reading the actual contents, its most likely a human who is doing the programming.

If I wanted to represent a person having a phone number in a Java class I would probably write "final String phoneNumber;" vs. "final String variable1;" Otherwise anyone who had to use my API would probably get fed up and go find something else to use.

Posted by Leonard at Tue Aug 28 2007 10:43

Choosing good URLs is a way of bridging the gap between the user's desire and the HTTP request the client ends up making. It does this by making it easy for the user to hard-code their desire into the client. When you start getting into ways of bridging the gap automatically, good URLs become less useful (relatively speaking) and semantic cues become more useful.

Posted by Leonard at Tue Aug 28 2007 10:45

Of course, that's not an excuse for slacking off and creating terrible URLs.

Posted by Scott Battaglia at Tue Aug 28 2007 14:45

oh man...I was hoping for a good reason to use randomly generated URLs ;-)


[Main] [Edit]

Unless otherwise noted, all content licensed by Leonard Richardson
under a Creative Commons License.