API Management

RESTful API Design: tips for search

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


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


Formatted results

For search or for any of the action oriented (non-resource) responses, you can prepend with the format as follows: