The general form of an URL is
scheme://domain:port/path?query_string#fragment_id
So you propose two URLs:
- search by
query_string
- search by last
path
segment
Search by query_string
I recommend to name the collection cars
, not search-cars
. As you write in your question, URLs identify resources. The cars
resource identifies the collection of all cars. I have no idea what collection a resource called search-cars
would identify.
GET http://api.test.com/cars
would return the collection of all cars.
GET http://api.test.com/cars/123
would return the car identified by 123
.
GET http://api.test.com/cars?color=blue&year=2013
would return the collection of all blue cars build in 2013.
Search by path
Your second URL
GET http://api.test.com/cars/{"color":"blue","year":"2013","make":"toyota"}
would make the query (JSON) a part of the path. To make the two examples equal, I suppose to make the JSON a query parameter:
GET http://api.test.com/cars?search={"color":"blue","year":"2013","make":"toyota"}
JSON vs. named query parameters
Most REST frameworks support mapping of query params to method parameters.
Most REST frameworks allow you to map a path segment to a method parameter. And, again, most REST frameworks allow you to map JSON to an object or a simple dictionary.
What makes JSON harder to use is the need to escape the "{}
characters:
{"color":"blue","year":"2013","make":"toyota"}
becomes
%7B%22color%22%3A%22blue%22%2C%22year%22%3A%222013%22%2C%22make%22%3A%22toyota%22%7D
which is not very nice.
Summary
- You can use both the
query_string
and thepath
of the URL to identify a resource. Search parameters are better placed in thequery_string
because the?
can mentally be translated to theWHERE
of SQL. - Don't use JSON in URLs because escaped JSON is hard to read.