RESTful API Design: tips for search
Brian Mulloy
In our latest post about pragmatic REST API design, let's talk about search.
What about searching?
While a simple search could be modeled as a resourceful API (for example, dogs/?q=red), a more complex search across multiple resources requires a different design.
This will sound familiar if you've read the aforementioned API design tip about using verbs not nouns when results don't return a resource from the database - rather the result is some action or calculation.
If you want to do a global search across resources, I suggest you follow the Google model
Global search
/search?q=fluffy+fur
Here, search is the verb; ?q represents the query.
Scoped search
To add scope to your search, you can prepend with the scope of the search. For example, search in dogs owned by resource ID 5678
/owners/5678/dogs/search?q=fluffy+fur
Formatted results
For search or for any of the action oriented (non-resource) responses, you can prepend with the format as follows:
/search.xml?q=fluffy+fur
