Re: API Pagination limit

[Philippe Mougin <[e-mail]>]

Le 14 juil. 2011 à 17:29, Karl Dubost a écrit :

> Hi,
> 
> About API and too large response limit.
> Jon Masse (cced) asked me a question about API and the right HTTP Code to send back to the client. 
> 
> Creating an API returning N posts starting at an index x
> with a limit of N <= 500.
> 
> Someone sends an HTTP GET with n=1000
> http://api.example.org/post?start=1&n=1000
> 
>    GET /post?start=1&n=1000 HTTP/1.1
>    Host: api.example.org
>    User-Agent: FooBar v1
>    Accept: application/json
> 
> What should the API developer send back?
> 
> * 200 OK and a Link for the pagination?
>  Link: </post?start=500&n=500>; rel="Next"
>  (but the client might not know it used an out of range value
> 
> * a 4xx to communicate that there is an out of range value?
>  (but which 4xx? It doesn't seem there is one appropriate.
>  403 doesn't seem right)
> 
> Thanks.

In such situations, I tend to do one of the following:

- Define the resource space in a way that avoid the error condition (e.g., explain that if n is > 500 it will be dealt with as if it was equal to 500). In the description of your resource space, you would specify that the resource at http://api.example.org/post?start={start}&n=500 is also identified by a number of other URLs, of the form http://api.example.org/post?start={start}&n={n}, where n is any integer greater than 500. If your resource space is defined like this, GET http://api.example.org/post?start=1&n=1000 would return a 200 OK and the actual representation of the resource (one with 500 posts).

or

- Define the resource space as exposing resources identified by URLs of the form http://api.example.org/post?start={start}&n={n} where n is an integer between 1 and 500. For the request you describe, answer with a 404 Not Found, because http://api.example.org/post?start=1&n=1000 would not identify an existing resource.

-Philippe