Question

I have to decide on a pagination strategy for returning results from a list. In particular, I am considering two approaches:

Example that lists results from 50 to 75:

Using query params: GET /items?start=50&limit=25

Pros

• Widely used
• Bookmarkable

Cons

• You will probably need to encode the URL ("&" character) to place it on XML response (complying with HATEOAS), and in that case the URL will not be very human friendly.

Embedded on the URL (page as a sub resource): GET /items/from-page-50-limited-to-25

Pros

• As human readable as needed (not required but seems like a good thing)
• No encoding necessary ever

Cons

• A little harder to build the URL client side
• Page is not really a sub resource of items, but a sub product of the listing items strategy

In your opinion, which would be the best REST practice approach?

Thanks in advance!

Answer 1

I believe you pointed out what is best practice by doing the research and saying that the first of you options is widely used. It is also the option I believe best conforms to how the query component is meant to be used. In RFC 3986, it states

The query component contains non-hierarchical data that, along with
data in the path component (Section 3.3), serves to identify a
resource

(from Querystring in REST Resource url).

Another way to look at it is that your second option is saying that /items/from-page-50-limited-to-25 is a unity resource/entity as well as is /items/from-page-1-limited-to-25. For me it’s more natural to think that /items is it unique resource where I can get a selection of the collection.