Option to use Link: header instead of page/total_pages/objects keys

[Xion]

GET requests to endpoints returning multiple results (GET_MANY) currently use the following pagination technique:

{
  "num_results": 6,
  "total_pages": 3,
  "page": 1,
  "objects": [
    {"name": "Jeffrey", "id": 1},
    {"name": "John", "id": 2}
  ]
}

The page and total_pages fields, as well as the whole ?page=N URL scheme are quite specific to Flask-Restless and have to be specifically accounted for by the client. However, there exists an arguably more standard way of doing pagination in REST APIs, which is implemented e.g. by GitHub's API -- using Link headers in HTTP responses, e.g.:

Link: /api/people?page=2; rel=next

It'd be nice if F-R supported this approach as an option (to APIManager). Right now there exists a convoluted workaround, but it requires reparsing the JSON response in after_request handler and constructing the header by ourselves, which is obviously suboptimal.

[jfinkels]

Your client should be getting those Link headers: see the test_pagination_links test function: https://github.com/jfinkels/flask-restless/blob/master/tests/test_views.py#L1551

Perhaps this is a documentation bug?

[jfinkels]

I have the same information appearing in both the headers and the JSON data for the sake of redundancy.

[Xion]

Oh, it totally appears so. As far as I could see, the documentation makes no mention of Link header whatsoever.

[jfinkels]

That's also why I have issue #349.

[eugene-eeo]

Maybe this is already resolved/fixed in some separate issue, but note that (perhaps only on development?) the Link headers are incorrect and do not include the query (URL prefixes truncated):

GET /api/event?q={"filters":[{"name":"year","op":"eq","val":2000}]}

HTTP/1.1 200 OK
Link: </api/event?page=2&results_per_page=30>; rel="next",
      </api/event?page=9&results_per_page=30>; rel="last"

I am not too sure what are the current "best practices" but one would usually expect to be able to traverse the pages without having to do any manual URL juggling and just follow the Link headers. I would expect the links to be:

/api/event?q=?q={...}&page=2&results_per_page=30