(API) Missing "Link" header for pagination

[tateisu]

The description of many API has "Pagination" section like as:

https://docs.joinmastodon.org/api/rest/timelines/#pagination-1

This API returns Link headers containing links to the next and previous page. However, the links can also be constructed dynamically using query params and id values.

https://docs.joinmastodon.org/api/rest/favourites/#pagination

This API returns Link headers containing links to the next and previous page. Since it is using an internal ID, it is not possible to dynamically generate query parameters to paginate. You must rely on the Link header.

Especially in case of some API, we can't know pagenation key from data array. For example, /api/v1/favourites returns user's favourites order by "favourite id" (nearly equals to favourited time order, but ID is unique.) , but its "favourite id" is not exposed in ID in data array.

Even in other cases, the boundary indicated by the Link header may be outside of the data array. They occur when items are excluded from the DB query result by filtering.

The client app should always paginate based on the Link header, not from the data array.

For more Information about Link header, there is RFC standard https://tools.ietf.org/html/rfc5988
that referenced in Mastodon's old document https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#notes .

For most GET operations that return arrays, the query parameters max_id and since_id can be used to specify the range of IDs to return. API methods that return collections of items can return a Link header containing URLs for the next and prev pages. See the "Link header RFC" for more information.

[tateisu]

If the Link header missing "next" or "prev" relation, it means "end of list".
for example. reading home timeline.
Its Link header may not has "next" relation because timeline always have old end.
But Link header always has "prev" relation because timeline may have newer posts when next request.

[dansup]

@tateisu Added in 8752d21

[tateisu]

oh, this implement does not indicate the id of read range.

[dansup]

This has been fixed!