How core is doing it

• Core's REST API search endpoint allows a single limit request parameter with a default value of 50 and an allowed maximum of 100
• No jumping to pages of the result
• See docs: https://www.mediawiki.org/wiki/API:REST_API/Reference#Parameters

Best practise for REST APIs

• Three different methods are described:
  1. Page based pagination: uses limit for the number of records per pages, offset for the starting point
     • This is also described using parameters page and size, which I think is equivalent
  2. Keyset pagination: uses an indexed column (like id or date) to fetch the next set of records, typically using parameters like from_id or created_after
     • Better performance in SQL databases when the query can be designed using a specific WHERE clause on an indexed collumn, rather than LIMIT and OFFSET
     • Not for our use case of search results
  3. Cursor based pagination: uses a unique identifier instead of an offset and with each response, the server will return the cursor pointing to the next page
     • More efficient than offset-based pagination and especially useful if data is modified between requests
     • Not for our use case of search results
• See https://ignaciochiazzo.medium.com/paginating-requests-in-apis-d4883d4c1c4c for a random blog post

REST API proposal

• Discusses page based and keyset based pagination
• Takes a decision in favour of page based pagination with paramaters page, per_page, offset
• See https://github.com/wmde/wikibase-rest-api-proposal/blob/master/DECISION-RESEARCH.md#pagination

Conclusion

• Do page based pagination with a limit
• If more than the first n results should be made available, use an offset or page parameter
• This is also how WikibaseEntitySearcher chunks its search results