diff --git a/aip/general/0158.md b/aip/general/0158.md index 7eb578e8f4..6ed881e211 100644 --- a/aip/general/0158.md +++ b/aip/general/0158.md @@ -110,9 +110,10 @@ For example: first 50 results were returned on the first page) and a `skip` value of `30` returns a single page of results starting with the 81st result. -If a `skip` value is provided that causes the cursor to move past the end of -the collection of results, the response **must** be `200 OK` with an empty -result set, and not provide a `next_page_token`. +If a `skip` value is provided that cannot be fulfilled e.g. due to latency of +querying a massive data set, the response **must** be `200 OK` with an empty +result set. If it is _known_ to put the cursor beyond the total size of the +collection, the response **must not** include a `next_page_token`. ### Opacity @@ -176,8 +177,23 @@ paginate) is reasonable for initially-small collections. [list]: ./0132.md +## Rationale + +### Degraded `skip` response + +Large collections, complex queries, and globally distributed data can all +contribute to a paginated method being unable to quickly or confidently fulfill +a given `skip` request. Backend queries can timeout, data collation can take +time, and the end user experience need not suffer as a result. In such cases, +the pagination interface can be leveraged to keep the client engaged by +providing a `next_page_token`, while the service collects an appropriate result. +When the service has definitively determined that the requested `skip` exceeds +the available results, the pagination interface is again applied and +`next_page_token` is omitted to signal the end of results. + ## Changelog +- **2025-07-08**: Clarify degraded skip response guidance - **2020-05-24**: Clarified that adding pagination breaks client libraries. - **2020-05-13**: Added guidance for skipping results.