What should REST service return if client doesn't specify the range of a large collection

Question

We are designing a Web service and want to ensure its REST compliance. Some GET requests result in a response that contain a collection of items. A client may not be aware of how large is this collection, and some collections may grow from small (retrievable at once) to large (require pagination).

So what a REST Web service should return when it receives a GET request like "/companies/contoso/employees"? Some companies may have small number of employees, others require result pagination. I can think of the following alternatives:

• Return 200 with no employee information but with hypermedia links clarifying how to specify ranges;
• Return 4xx (I don't like this because the error status code doesn't give client a hint of how it should properly build the URI)
• Return 200 with the number of items according to default range settings. I don't like this either because client may think the response contains the whole collection, not just a subset
• If a result is small, return it with 200, otherwise return 4xx
• Assume that default range setting is 0 items and return 200 with 0 items and hypermedia links clarifying how to change the range

I lean towards the last alternative: assume that the cliens wants first 0 items. Is this reasonable approach according to REST design guidelines?

Answer 1

I don't believe this is a question of REST compliance as much as it is a question about your API in general. One could argue that a blanket GET with no parameters could be expected to return everything, however that's probably not a great implementation for your own sake.

Unlike command line tools, you are not required to provide proper usage details upon improper invocation. It's perfectly acceptable to merely return 400 for a bad request. You may like to provide more details but the harsh reality is that you may get a poorly implemented client who is making that request 5000 times a second and you want to do as little processing as possible. Your documentation should provide them the proper structure.

That being said, if it makes sense from your requirements that you return a sensible set of defaults then that is also fine.

However, it really depends on if you as an API provider believe that a GET without additional parameters is a valid request or not. That is completely up to you. Personally, I'd stick with the 400 just to force clients to be more specific and protect your resources.