RESTful URL design for search

by

I’m looking for a reasonable way to represent searches as a RESTful URLs.

The setup: I have two models, Cars and Garages, where Cars can be in Garages. So my urls look like:

/car/xxxx
  xxx == car id
  returns car with given id

/garage/yyy
  yyy = garage id
  returns garage with given id

A Car can exist on its own (hence the /car), or it can exist in a garage. What’s the right way to represent, say, all the cars in a given garage? Something like:

/garage/yyy/cars     ?

How about the union of cars in garage yyy and zzz?

What’s the right way to represent a search for cars with certain attributes? Say: show me all blue sedans with 4 doors :

/car/search?color=blue&type=sedan&doors=4

or should it be /cars instead?

The use of “search” seems inappropriate there – what’s a better way / term? Should it just be:

/cars/?color=blue&type=sedan&doors=4

Should the search parameters be part of the PATHINFO or QUERYSTRING?

In short, I’m looking for guidance for cross-model REST url design, and for search.

[Update] I like Justin’s answer, but he doesn’t cover the multi-field search case:

/cars/color:blue/type:sedan/doors:4

or something like that. How do we go from

/cars/color/blue

to the multiple field case?

12 Answers
12

For the searching, use querystrings. This is perfectly RESTful:

/cars?color=blue&type=sedan&doors=4

An advantage to regular querystrings is that they are standard and widely understood and that they can be generated from form-get.

Leave a Comment