2

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!

Community
  • 1
  • 1
NahueDV
  • 23
  • 1
  • 3
  • URLs shouldn't (have to) be built client side if you are following Hypermedia as the engine of application state: http://www.infoq.com/articles/mark-baker-hypermedia – Marjan Venema Jul 25 '12 at 06:23
  • I quite agree with you in general, but what about asking for a list of items and adding filter information? For example, as a client perhaps you would need items created in a certain time frame, so, client side, you have to add those params to the call to filter the return values. HATEOAS is more about what can you do next, once you have your resource at hand. – NahueDV Jul 25 '12 at 13:13
  • We are considering a form of templated HATEOAS for that. Admittedly that is all still in a brainstorm phase. The thinking currently is along these lines: filter URI is actually a URI template: `/questions[/tagged/{tagnames}][/daterange/{start},{end}][/users/{names or ids}]`. It will be supported by `/tags` and `/users` URIs to supply the list of currently known tags and users. We still need to think about how to present/structure this information in responses so clients have a standardized way of combining the URI template with values from the linked lists as they are selected by users. – Marjan Venema Jul 25 '12 at 13:34

1 Answers1

2

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.

Community
  • 1
  • 1
Paul DelRe
  • 4,003
  • 1
  • 24
  • 26
  • Both approaches appear to conform the RFC. Personally, I like the second approach. Having said that, I believe I will use the first one. Why? Taking into consideration the constraints of the problem (pagination) both answers are somewhat equivalent, but if later I want to add more filters then, as you said, definitively the first approach will feel more natural (eg. GET /items?start=50&limit=25&color=blue instead of GET /items/from-page-50-limited-to-25?color=blue). – NahueDV Jul 25 '12 at 13:28