standard way of encoding pagination info on a restful url get?

Question

I think my question would be better explained with a couple of examples...

GET http://myservice/myresource/?name=xxx&country=xxxx&_page=3&_page_len=10&_order=name asc

that is, on the one hand I have conditions ( name=xxx&country=xxxx ) and on the other hand I have parameters affecting the query ( _page=3&_page_len=10&_order=name asc )

now, I though about using some special prefix ( "_" in thes case ) to avoid collisions between conditions and parameters ( what if my resourse has an "order" property? )

is there some standard way to handle these situations?

--

I found this example (just to pick one) http://www.peej.co.uk/articles/restfully-delicious.html

GET http://del.icio.us/api/peej/bookmarks/?tag=mytag&dt=2009-05-30&start=1&end=2

but in this case condition fields are already defined (there is no start nor end property)

I'm looking for some general solution...

-- edit, a more detailed example to clarify

Each item is completely indepent from one another... let's say that my resources are customers, and that (luckily) I have a couple millions of them in my db.

so the url could be something like

http://myservice/customers/?country=argentina,last_operation=2009-01-01..2010-01-01

It should give me all the customers from argentina that bought anything in the last year

Now I'd like to use this service to build a browse page, or to fill a combo with ajax, for example, so the idea was to add some metada to control what info should I get

to build the browse page I would add

http://...,_page=1,_page_len=10,_order=state,name

and to fill an autosuggest combo with ajax

http://...,_page=1,_page_len=100,_order=state,name,name=what_ever_type_the_user*

to fill the combo with the first 100 customers matching what the user typed...

my question was if there was some standard (written or not) way of encoding this kind of stuff in a restfull url manner...

Answer 1

While there is no standard, Web API Design (by Apigee) is a great book of advice when creating Web APIs. I treat it as a sort of standard, and follow its recommendations whenever I can.

Under "Pagination and partial response" they suggest (page 17):

Use limit and offset

We recommend limit and offset. It is more common, well understood in leading databases, and easy for developers.

/dogs?limit=25&offset=50

Answer 2

There's no standard or convention which defines a way to do this, but using underscores (one or two) to denote meta-info isn't a bad idea. This is what's used to specify member variables by convention in some languages.

Answer 3

---

Note: I started writing this as a comment to my previous answer. Then I was going to add it as an edit, but I think that it belongs as a separate answer instead. This is a completely different approach and a separate answer in its own right since it is a different approach.

---

The more that I have been thinking about this, I think that you really have two different resources that you have to deal with:

1. A page of resources
2. Each resource that is collected into the page

I may have missed something (could be... I've been guilty of misinterpretation). Since a page is a resource in its own right, the paging meta-information is really an attribute of the resource so placing it in the URL isn't necessarily the wrong approach. If you consider what can be cached downstream for a page and/or referred to as a resource in the future, the resource is defined by the paging attributes and the query parameters so they should both be in the URL. To continue with my entirely too lengthy response, the page resource would be something like:

http://.../myresource/page-10/3?name=xxx&country=yyy&order=name&orderby=asc

I think that this gets to the core of your original question. If the page itself is a resource, then the URI should describe the page so something like page-10 is my way of saying "a page of 10 items" and the next portion of the page is the page number. The query portion contains the filter.

The other resource names each item that the page contains. How the items are identified should be controlled by what the resources are. I think that a key question is whether the result resources stand on their own or not. How you represent the item resources differs based on this concept.

If the item representations are only appropriate when in the context of the page, then it might be appropriate to include the representation inline. If you do this, then identify them individually and make sure that you can retrieve them using either URI fragment syntax or an additional path element. It seems that the following URLs should result in the fifth item on the third page of ten items:

http://.../myresource/page-10/3?...#5
http://.../myresource/page-10/3/5?...

The largest factor in deciding between these two is how strongly coupled the individual item is with the page. The fragment syntax is considerably more binding than the path element IMHO.

Now, if the item resources are free-standing and the page is simply the result of a query (which I think is likely the case here), then the page resource should be an ordered list of URLs for each item resource. The item resource should be independent of the page resource in this case. You might want to use a URI that is based on the identifying attribute of the item itself. So you might end up with something like:

http://.../myresource/item/42
http://.../myresource/item/307E8599-AD9B-4B32-8612-F8EAF754DFDB

The key deciding factor is whether the items are freestanding resources or not. If they are not, then they are derived from the page URI. If they are freestanding, then they should have their are defined by their own resources and should be included in the page resource as links instead.