Searching REST API

[NotionCommotion]

Say I have the following API.

GET /users # list of users
GET /users/1 # get user with id 1
POST /users # create new user
PUT /users/1 # modify user with id 1
DELETE /users/1 # delete user with id 1

GET /users will return the following:

[
   {firstname:"John",lastname:"Doe",email:"johndoe@example.com",phone:"(800) 555-1212"},
   {firstname:"Jane",lastname:"Doe",email:"janedoe@example.com",phone:"(800) 555-2121"}
]

Now I wish to return only users who's name starts with "Joh" and the client only needs first and last names.

 

GET /users/Joh won't work as there is no user "Joh".  It is my understanding that I should not use verbs and NOT do something like GET /searchUsers/Joh, correct?  Should it be GET /users?term=Joh?  For the limited data, should I just return everything and let the client deal with it, or have the client send another parameter in the URL to limit such as GET /users?term=Joh&format=minimal?

Edited June 22, 2016 by NotionCommotion

[Muddy_Funster]

I don't understand what the question is here.  Do you only ever want to return users whose first name starts "joh" or do you want it as an option, what are you using to as a data store? what's the issue with scripting the query dependant on the get value?  such as :

 

$v = trim($_GET['value']);
if($v == ''){
//return full dataset
}
elseif (is_int((int)$v)){
//return record with ID number
}
else{
//return results of first name search
}

[NotionCommotion]

 

I don't understand what the question is here.  Do you only ever want to return users whose first name starts "joh" or do you want it as an option, what are you using to as a data store? what's the issue with scripting the query dependant on the get value?  such as :

 

Hi Muddy,

 

The returned users will be based on what the user types, and is an option and not always "joh".

 

The question is regarding REST endpoints, and whether the get all users and search users should be the same endpoint.  I've also read posts where people stated POST should be used for searches so that query parameters could be included in the body, but that just doesn't seem right.

[Psycho]

You could pass the search criteria on the query string of the GET method

 

E.g.

 

GET /users?name=Joh

[NotionCommotion]

 

You could pass the search criteria on the query string of the GET method

 

 

Thanks Psycho,  That is what I was thinking, but wasn't sure.