The best way to perform restful search

Question

So I have a theoretical question based on a lot of research that I have done recently with regards to REST API interfaces.

Firstly I understand that in REST, resources should be nouns and not verbs and each resource should be decoupled from the next resource, however the resources can return the same entities or collection of entities, depending on the purpose of the resource.

My focus however is performing restful search.

In all the research I have done, the most common solution I have come across is the use of parameters in the URL

api.test.com/search-cars?param1=val1&param2=val2

Now while this is standard practice and is not truly breaking the rules of REST, why is it that no one represents the search parameters as an id (possibly in the form of JSON)

api.test.com/cars/{"color":"blue","year":"2013","make":"toyota"}

If I look at cars as a resource and represent my id as a JSON, I could easily say that I truly have a finite number of cars thus a finite and unique number of id's.

Further more this promotes pure rest by conforming to "resource/id"

What are the benefits and downsides to using parameters as in the first example?

What are the benefits and downsides to using JSON as an id with the "filters" as in the second example?

All your comments would be really helpful as I need to take a final decision on how to move forward with the first resource of my API. Also, I need to have a strong argument for my boss explaining why I decided on either of the methods.

Answer 1

The general form of an URL is

scheme://domain:port/path?query_string#fragment_id

So you propose two URLs:

1. search by query_string
2. 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 the path of the URL to identify a resource. Search parameters are better placed in the query_string because the ? can mentally be translated to the WHERE of SQL.
• Don't use JSON in URLs because escaped JSON is hard to read.