Many API responses, particularly to list and search methods, are paginated (AIP-158). Users calling these methods are then required to implement their own pagination logic, which is common boilerplate.
Client libraries may provide automatic resolution of pagination (meaning that it performs requests in the background on an as-needed basis).
Pagination can be inferred for an RPC when all of the following conditions are met:
- The request message contains an
- The request message contains a
- The response message contains a
- The response message contains one non-primitive
Client library generators implementing this feature must ensure that it is a backwards-compatible change to add client-side pagination functionality where it was previously absent.
For the client library to implement pagination (as defined by AIP-158), it
should use the
next_page_token value from the response message to
page_token value of an otherwise-identical request message,
continuing indefinitely until the
next_page_token value is empty.
Important: Client libraries that are implementing automatic resolution of pagination should only perform requests for future pages on an as-needed basis, and avoid greedily resolving potentially long and unnecessary result sets.
Client libraries that are implementing automatic pagination must still provide access to the individual fields on the response message, in the usual fashion.
Note: If the response message has more than one non-primitive
field, the first one (in order of appearance in the file and field number) is
used. If the first field by order of appearance in the message and the first
field by field number do not match, code generators that implement automatic
pagination should fail with an error.