0

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.

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:

GET /api/users/     //Returns a collection of all users
GET /api/users/1/  //Returns all data for a single userid

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.

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.

Then we have the case where we want to pass in an email address and get back a userid.

It seems all of these cases call for some additional parameters which I haven't normally seen demonstrated in other web service examples.

GET /api/users/?max=100&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&email=someone@microsoft.com
//If found, returns the userid for the corresponding email address

I'm uncertain if the URL format I'm showing here is proper but that's really outside the scope of my actual question.

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?

HK1
  • 11,941
  • 14
  • 64
  • 99
  • You can do this or specify your parameters as part of the body of the request. But this way works just fine and you are not violating the REST architecture. – Henrique Barcelos Jan 30 '14 at 18:46
  • I bolive the rest principle is to narrow your call using something like this GET /api/users/max/100/firstname/mike – uacaman Jan 30 '14 at 18:49
  • @uacaman So does REST dictate that you must use so-called Pretty URL's, even for all parameters? – HK1 Jan 30 '14 at 18:51
  • These links might help: http://stackoverflow.com/questions/776448/pagination-in-a-rest-web-application http://stackoverflow.com/questions/978061/http-get-with-request-body – Brian Kelly Jan 30 '14 at 19:41
  • I dont think there is the Pretty URL in the REST. All the is needed is the URI. Makes no sense to mix URL as parameters like /api/users/1/ with max=100&firstname=mike. Is way easier to use one or the other. From any point of view both are valid but since REST about resources it makes sense to navigate through resources using what everyone is already use. – uacaman Jan 30 '14 at 19:42

0 Answers0