Why providing pagination information in API response?

Question

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?

Answer 1

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.