hypothesis / hypothesis/h

Add explicit link to next page of results in search API

Open
#7,841 6 comments 0 reactions 0 assignees View on GitHub
feature request
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.