REST API: How to search for other attribute

I use node.js as REST API. There are following actions available:

  1. /contacts, GET, finds all contacts
  2. /contacts, POST, creats new contact
  3. /contacts/:id, GET, shows or gets specifiy contact by it's id
  4. /contacts/:id, PUT, updates a specific contact
  5. /contacts/:id, DELETE, removes a specific contact

What would now be a logic Route for searching, quering after a user? Should I put this to the 3. route or should I create an extra route?

I'm sure you will get a lot of different opinions on this question. Personally I would see "searching" as filtering on "all contacts" giving:

GET /contacts?filter=your_filter_statement

You probably already have filtering-parameters on GET /contacts to allow pagination that works well with the filter-statement.

EDIT: Use this for parsing your querystring:

var url = require('url');

and in your handler ('request' being your nodejs http-request object):

var parsedUrl = url.parse(request.url, true);
var filterStatement = parsedUrl.query.filter;

Interesting question. This is a discussion that I have had several times.

I don't think there is a clear answer, or maybe there is and I just don't know it or don't agree with it. I would say that you should add a new route: /contacts/_search performing an action on the contacts list, in this case a search. Clear and defined what you do then.

GET /contacts finds all contacts. You want a subset of all contacts. What delimiter in a URI represents subsets? It's not "?"; that's non-hierarchical. The "/" character is used to delimit hierarchical path segments. So for a subset of contacts, try a URI like /contacts/like/dave/ or /contacts/by_name/susan/.

This concept of subsetting data by path segments is for more than collections--it applies more broadly. Your whole site is a set, and each top-level path segment defines a subset of it: http://yoursite.example/contacts is a subset of http://yoursite.example/. It also applies more narrowly: /contacts/:id is a subset of /contacts, and /contacts/:id/firstname is a subset of /contacts/:id.