In the most post in this series about Pragmatic REST API design, I talked about handling responses that don't involve resources. This time, a somewhat related topic - 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. what about responses that don’t involve resources?
If you want to do a global search across resources, I suggest you follow the Google model
Here, search is the verb;
?q represents the query.
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
For search or for any of the action oriented (non-resource) responses, you can prepend with the format as follows:
Next: what about counts?