REST and complex search queries

Question

I\'m looking for a robust way to model search queries in a REST api.

In my api, you can specify the search criteria in the URI of a resource using query parameters.<

Answer 1

Whenever I face these problems, I ask myself "How would I present this to a user, if I was creating a traditional webpage"? The simple answer is that I wouldn't present those sort of options in a single page. The interface would be too complex; however what I could do is provide an interface that allowed users to build up more and more complex queries over a number of pages and that's the solution I think you should go for in this case.

The HATEOAS constraint specifies that we must include the hypermedia controls (links and forms) in our responses. So let's say we have a paginated collections of cars at /cars with a search option, so that when you get /cars it returns something like (BTW I'm using a custom media-type here, but the forms and links should be pretty obvious. Let me know if it isn't):

    ...
    ...
    ...
    ...
    ...
    
    
        
        
            
            
            
        
        
            
            
            
        
    
    
        
        
            
            
            
        
    

So just say we search for white cars, we would GET /cars?color=white and we might get back something like:

    ...
    ...
    ...
    
    
        
        
            
            
            
        
        
            
            
            
        
    
    
        
        
            
            
            
        
    

This result then let's us refine our query. So just say we wanted white cars but not "off-white" cars, we could then GET '/cars?color=white&color2=off-white&color2-logic=not', which might return

    ...
    ...
    ...
    
    
        
        
            
            
            
        
        
            
            
            
        
    
    
        
        
            
            
            
        
    

We could then further refine our query, but the point is that at each step along the way, the hypermedia controls tells us what is possible.

Now, if we think about the search options for cars, the colors, doors, makes and models aren't unbounded, so we could make the options more explicit by providing enumerations. For instance

    ...
    
        
            
            
            
            
        
        
            
            
            
        
    

However the only white cars that we have might be 2 and 4 door, in which case GETing /cars?color=white might give us

    ...
    
        
            
            
        
        
            
            
            
        
    

Similarly, as we refine the colors, we might find their are only a few options, in which case we can switch from providing a string search, to providing an enumeration search. e.g., GETing /cars?color=white might give us

    ...
    
        
            
            
            
        
        
            
            
            
        
    
    ...

You could do the same for other search categories. For instance, initially you wouldn't want to enumerate all the makes, so you would provide some sort of text search. Once the collection has been refined, and there are only a few models to pick from, then it makes sense to provide an enumeration. The same logic applies to other collections. For instance you wouldn't want to enumerate all of the cities in the world, but once you have refined the area to 10 or so cities, then enumerating them can be very helpful.

Is there a library that will do this for you? None that I know of. Most I've seen don't even support hypermedia controls (i.e., you've got to add the links and forms yourself). Is there a pattern you can use? Yes, I believe the above is a valid pattern for solving this sort of problem.