How to design a RESTful URL for search with optional parameters?

Question

If I have to create a URL in my RESTful web service, which would be used by my clients to search all businesses by their fields where the fields are optional, what would the URL look like?

A business can be search by their name alone, name and phone number or name, phone number and contact e-mail.

Answer 1

Chandru, think of the list of all the businesses like of a set of entities with attributes. You can create URIs that identify (select) a subset by the use of parameters in the URI.

Commonly this is done by query string parameters (the stuff after the '?') but you can also specify parameters as path segments or matrix URIs.

The most typical means to do this would be something like

• http://foo.org/service/businesses/?name=acme or
• http://foo.org/service/businesses/?name=acme&phone=12345 or
• http://foo.org/service/businesses/?name=acme&[email protected] ('@' would need URL encoding of course)

It is conceptually similar to an SQL select clause.

Parameters in path segments or matrix parameters have an impact regarding the indexing possibilities (e.g. matrix parameters allow you to filter at multiple levels because the hierarchy can continue after wards, which it cannot with query parameters). I suggest you make that a different question if you are concerned with it.

Example:

http://foo.org/service/businesses/france/name=acme;city=paris/latest/?contact=xxx

Jan