The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

RESTful URI

I'm fiddling with my first RESTful Web Service trying to train my brain to see things properly.  I'm having some trouble figuring out the best way to access resources based on parametric information.  There seems to be two approaches available, and I'd like to know which is best and why.

Specifically, we can use the built in support for parameters and have URIs like this:

http://Service/MyResources?P1=0&P2=5&P3=12

The other approach seems to be to embed the parametric information directly into the address like:

http://Service/MyResources/0/5/12  or
http://Service/MyResources/P1/0/P2/5/P3/12

To me, the first one seems best since it seems like that's what the support for parameters is for.  On the other hand, I don't understand the HTTP protocol or infrastructure enough to know if the other solution isn't better.  I see this second version popping up in a lot of places.  For example, many of the search URLs on Amazon seem to have parametric information embedded in the address part of the URL.  I assume this is done for a reason.

Can anyone shed any light?  Thanks in advance.
RESTful Wannabe Send private email
Monday, May 14, 2007
 
 
http://Service/MyResources?P1=0&P2=5&P3=12

That looks like you are searching where in REST a URI indicates a resource, so it should have a clean single ID, not a path.
son of parnas
Monday, May 14, 2007
 
 
Perhaps I wasn't clear about what I was asking.  I'm asking about the case where I want to obtain a resource based on properties of the resource, not the ID of the resource.  For example, suppose my service manages books.  One of the resources that I might be interested in is the set of books by ROBERT JORDAN, for example.  This resource won't be managed as an explicit resource by the service - it is constructed implicitly when the right request is received.

So, it is better to access this resource as

http://books?fname=ROBERT&lname=JORDAN

or

http://books/fname/ROBERT/lname/JORDAN

or something else entirely?

Searching the web doesn't really turn up anything authoritative that I can see.
RESTful Wannabe Send private email
Monday, May 14, 2007
 
 
I would have preferred blah.com/jordan/robert or blah.com/author/jordan/robert
There is no real need for the lname/fname part - all it is doing is making it look like a cgi param.
Also by using surname first it should be easy to return all the jordans if you don't have the first name.
Martin Send private email
Monday, May 14, 2007
 
 
"There is no real need for the lname/fname part - all it is doing is making it look like a cgi param."

hmmmm, I was thinking it might be useful to include lname/fname for two reasons:

1.  It provides some built in documentation for the link format
2.  It allows me to have other variations which take two parameters which are not last/first name.  Perhaps something like title/edition or something:

http://blah/books/lname/jordan/fname/robert and
http://blah/books/title/knife of Dreams/edition/1

without the lname business it would seem to be hard to make sense of the parameters.

I found this link which makes a good case for avoiding the parameter stuff:

http://www.megginson.com/blogs/quoderat/2007/02/15/rest-the-quick-pitch/

so, unless I stumble over something more compelling, I think that's the approach I will take.  Thanks!
RESTful Wannabe Send private email
Tuesday, May 15, 2007
 
 
My examples follow the following rules, which should be documented

/author/$LASTNAME lists all authors with the lastname
/author/$LASTNAME/$FIRSTNAME list an author's books
/author/$LASTNAME/$FIRSTNAME/$CATEGORY author's books in a certain category
/isbn/$ISBN gets info about a specific book
/user/$username gets info about a specific user
 ...etc.
Totally Agreeing
Tuesday, May 15, 2007
 
 
One reason parametric info is embedded inside a url is because it will make the search engines think they are static pages and make them follow the links on that page.

You can transform embedded params using rewrite rules in .htaccess.

RewriteEngine On
RewriteRule /author-([^/]+)/c([^/]+)/f([^/]+)$ /searchbyauthor.asp?author=$1 [L]
RewriteRule /lname-([^/]+)/fname-([^/]+)$ /searchbyname.asp?lname=$1&fname=$2 [L]
RewriteRule /isbn-([^/]+)$ /searchbyisbn.asp?isbn=$1 [L]
Donald Duck
Tuesday, May 15, 2007
 
 
That's fairly old advice.  Search engines no longer make any distinction between pages with query parameters and those that don't.  Otherwise, no forum posts anywhere would ever be indexed.
Almost H. Anonymous Send private email
Tuesday, May 15, 2007
 
 
URIs that contain query parameters are still second-class citizens in many respects (see 13.9 of the HTTP 1.1 standard for an example). I generally only use query parameters to imply that the parameter values are being used as inputs to an algorithm.

That said, this whole issue is fairly subjective and has more to do with UI design than RESTfulness. I use a slash when two pieces of information form a hierarchy, a semicolon or comma when two pieces of information go together, and a query parameter when I want to imply the existence of an algorithm.  Here's how I'd do two of the URIs you mentioned:

/author/Jordan,Robert
/book/Knife of Dreams/edition/1

If you're interested, I talk about URI design in chapters 4 and 8 of my book "RESTful Web Services".
Leonard Richardson Send private email
Tuesday, May 15, 2007
 
 
"If you're interested, I talk about URI design in chapters 4 and 8 of my book 'RESTful Web Services'."

Thanks Leonard.  I actually ordered your book last month from Amazon.  Looked like it was set for publication on May 1st, but I've gotten a couple notes from Amazon asking me to accept a delayed shipment.  I think my current "deliver by" date is some time in August. 

Is the book available then, perhaps elsewhere than Amazon?
RESTful Wannabe Send private email
Tuesday, May 15, 2007
 
 
According to O'Reilly, Amazon's shipping emails are glitchy and you should get your book a lot sooner than August. In the meantime, you can read chapter 4 online:

 http://www.oreilly.com/catalog/9780596529260/
Leonard Richardson Send private email
Tuesday, May 15, 2007
 
 
Terry Lorber Send private email
Friday, May 18, 2007
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz