Subject: API Pagination limit

From: Karl Dubost <[email-masked]>
Date: Thu, 14 Jul 2011 11:29:52 -0400

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.

-- 
Karl Dubost - http://dev.opera.com/
Developer Relations & Tools, Opera Software

---

From: "Eric J. Bowman" <[email-masked]>
Date: Thu, 14 Jul 2011 10:23:58 -0600

>   (but which 4xx? It doesn't seem there is one appropriate.

200 is definitely wrong, 400 is the appropriate failure code, or use a
307 redirect (the post count may grow to accommodate the request, so
don't use 301).

-Eric

---

From: Philippe Mougin <[email-masked]>
Date: Fri, 15 Jul 2011 07:36:28 +0200

>  (but which 4xx? It doesn't seem there is one appropriate.

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