Add explicit link to next page of results in search API
- Dominant language
- Python
- Stars
- 3.2k
- Forks
- 459
- Avg merge
- 27d 1h
- Merged PRs (30d)
- 1
Description
The search API supports cursor-based pagination using the [`search_after` parameter](https://h.readthedocs.io/en/latest/api-reference/#tag/annotations/paths/~1search/get). The responses do not include an explicit link to the next page of results, so API clients have to figure out how to construct that themselves, and also how to tell when they have reached the end of the results. This has caused some problems:
- The lack of explicit "last page" indicator and an [h issue](https://github.com/hypothesis/h/issues/7840) with deleted annotations caused a [client bug](https://github.com/hypothesis/client/issues/5219) where in some rare cases it only fetches a subset of the annotations it should
- I have fielded several queries from users who had problems using `search_after` because they did not construct the next-page link correctly, or got confused by the fact that "after" refers to the order of entries in the results, and not necessarily "after" in a chronological sense. Providing an explicit link would avoid the need for manual construction for the most common use case, and also provide a live example of how the parameter is used.
What I would suggest we do is add an explicit "next page" link to the results, which is omitted for the last page. Some examples in other APIs:
- https://developer.atlassian.com/server/confluence/pagination-in-the-rest-api/ (uses `_links` object in JSON response)
- https://docs.github.com/en/rest/guides/using-pagination-in-the-rest-api?apiVersion=2022-11-28 (uses Link headers)
Of the approaches above, I think I would favor a field in the JSON response, as being easier to discover and to parse.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.