title: RESTful Web Service Needs Multiple Gets for Same Resource
body: <p>I'm writing a RESTful Web Service in PHP (no special frameworks but using PDO Prepared Statements) that consumes and returns JSON data. The problem I'm running into is needing some way to specify in more detail what a GET request is supposed to return. I think I understand how to accomplish what I want, but I'm not sure that my way would be in line with what true REST principles. I'd like to know if there's some standard way of handling the problem outlined below.</p>
  
  <p>Most (or maybe all) of the examples I have found so far assume that there are basically two standard GET requests for each domain/entity/resource as follows:</p>
  
  <pre><code>GET /api/users/     //Returns a collection of all users
  GET /api/users/1/  //Returns all data for a single userid
  </code></pre>
  
  <p>It seems we need more options than just this. Surely we will not return all data for all users on the first request, as there could be thousands of them. So we need to limit the amount of records being returned, and possibly which fields should be returned as well, depending on the context of the calling application.</p>
  
  <p>Then you have the issue where you build a UI that does a search so we need to be able to handle some incoming parameters for a search, and likely the output will be something like UserID, Username, FirstName, Lastname, etc., as opposed to outputting all fields.</p>
  
  <p>Then we have the case where we want to pass in an email address and get back a userid.</p>
  
  <p>It seems all of these cases call for some additional parameters which I haven't normally seen demonstrated in other web service examples.</p>
  
  <pre><code>GET /api/users/?max=100&amp;firstname=mike 
  //Returns a collection of up to 100 users who have the first name mike
  
  GET /api/users/1/  
  //Returns all data for a single userid
  
  GET /api/users/?get=userid&amp;email=someone@microsoft.com
  //If found, returns the userid for the corresponding email address
  </code></pre>
  
  <p>I'm uncertain if the URL format I'm showing here is proper but that's really outside the scope of my actual question.</p>
  
  <p>What I'd really like to know is how Web Services are supposed to be written when you need to be able to retrieve data using a variety of parameters such as number of records to be returned, context (or verb) which determines which fields are to be returned, and search parameters that should be used to narrow the result set?</p>