2

We are now designing our RESTful API and I have a question for how to expose the pagination information.

It seems some famous services like Github or Firefox Market Place having something like below in their API:

{ "meta": { "limit": 3, "next": "/api/v1/apps/category/?limit=3&offset=6", "offset": 3, "previous": "/api/v1/apps/category/?limit=3&offset=0", "total_count": 16 } }

My question is:

Why should the server give the complete next/previous url in the response?

It seem to me that the client is making the first request. So it knows what parameters it used to call (offset/limit/api version). It is easy for the client to figure out what is the next/previous url to call. Why bother to calculate the redundant urls and give it to the client?

Improve this question
3
  • use pagination protects you from a user taking all your resources with a large query. For example, limit the number of returned items to 20. You can either pass the page, for convenience to the user. Commented Jun 25, 2013 at 2:29
  • 2
    @Matt I think you've missed the precise question the OP is asking. It's "why provide URLs in the response when the client clearly knows how to generate them?" and not "why use pagination at all?" Commented Jun 25, 2013 at 2:30
  • @MattBall thanks for clarifying for me. What you said is exactly what I was going to type. Commented Jun 25, 2013 at 13:53

1 Answer 1

Reset to default
3

It's RESTful! That is specifically part of HATEOAS, or Hypermedia as the Engine of Application State.

Except for simple fixed entry points to the application, a client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.

and:

[HATEOAS] is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia.
...
A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server.

(Emphasis added)

It seem to me that the client is making the first request. So it knows what parameters it used to call (offset/limit/api version).

Yes, the client makes the first request, but that doesn't mean it knows anything about URL discovery, pagination, limit/offset parameters, etc.

Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

Thanks for your answer, Matt. Still I'm not sure why "that doesn't mean it knows anything about URL discovery, pagination, limit/offset parameters, etc." Since the client starts the request, it knows which page it's requesting (offset), how many items is on a page (limit) and what api version it is calling. Even the client doesn't persistent these info after request, the server could just echo the "offset", "limit" in the response rather than complete uri.
My guess for why the complete uri is given in the response is, maybe the API designers are fans of Atom protocol so RFC5005|ietf.org/rfc/rfc5005.txt is taken as a start point. But RFC5005 is different: it has first/next/pre/last all in the server response so the pagination is absolutely transparent to the client.
"Since the client starts the request, it knows which page it's requesting (offset), how many items is on a page (limit)" no, that's just not true. The first quote in my answer directly disputes that. The client does not necessarily know it's receiving a paginated response at all when it requests a list of things.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.