views:

718

answers:

4

I am designing a REST api that needs paging (per x) enforces from the server side.

What would be the right way to page through any collection of resources:

Option 1:

GET /resource/page/<pagenr>
GET /resource/tags/<tag1>,<tag2>/page/<pagenr>
GET /resource/search/<query>/page/<pagenr>

Option 2:

GET /resource/?page=<pagenr>
GET /resource/tags/<tag1>,<tag2>?page=<pagenr>
GET /resource/search/<query>?page=<pagenr>

If 1, what should I do with GET /resource? Redirect to /resource/page/0, reply with some error or reply with the exact same as /resource/page/0 without redirecting?

+2  A: 

With my limited understanding of what REST is about, then the following might be the "most" restful.

GET /resource/?page=<pageenr>&asof=<datetime>

Since the content of the representation would never change unexpectedly, and caching could be used.

But to actually answer your question, I think the parameter page is the preferred method.

Allain Lalonde
Not only that, but paging is not part of the resource. Whether you use paging or not, and in what form, does not change the resource, just the way you ask to see it. The same goes for sort order, and even filtering.
Dave Van den Eynde
@Dave Van den Eynde: That's wrong. RFC 3986 (URI Generic Syntax) states (Section 3.4): **"The query component contains non-hierarchical data that** *along with data in the path component (Section 3.3),* **serves to identify a resource** *within the scope of the URI's scheme and naming authority (if any)"* (my highlighting). Page two is a different resource than page 1. But in any case, it's irrelevant to the RESTfulness.
mogsie
By that RFC, the "fragment" part of the URI should be used for paging/sorting. But I seriously doubt that this RFC applies here. Have you tried this? I don't think browsers make a distinction between two URI's where only the fragment differs. Perhaps I should have worded that differently. If in a REST api the 'resource' is really what is identified by the PATH, then the QUERY can be used to complete the resource with paging/sorting. But what a 'resource' is to REST, differs from what a resource is in the context of a URI.
Dave Van den Eynde
A: 

I'd go with option (2). Why?

  1. You can later add page-size parameter to the query so the client can specify the page size.
  2. In case no page parameter was specified you can just return the first page (the default). In many cases you client might need only the first page, so it simplifies the protocol between client and server.
LiorH
+1  A: 

What the URI looks like is not the most important part. What you should be thinking about instead is how it is presented to the user. A page should for example have a link to the "next" page and another link to the "previous" page (if there is one). Take a look at RFC 5005 Feed Paging and Archiving

Bjorn
Why was this voted down? It's the right answer!
mogsie
Nice link - I hadn't seen that RFC before.
ladenedge
A: 

Maybe have a look at http://stackoverflow.com/questions/924472/paging-in-a-rest-collection

zehrer