Decorator for paged responses with page token

[santhoshramaraj]

Many server APIs interfacing with large data implement paging, where responses are returned in pages(batches) and a token is used to identify the current and next page to return.

Example, https://developers.google.com/gmail/api/reference/rest/v1/users.messages/list

GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages

pageToken query parameter is used to retrieve a specific page of results in the list.

{
  "messages": [
    {
      object (Message)
    }
  ],
  "nextPageToken": string,
  "resultSizeEstimate": integer
}

In most cases, the user interfacing with the client wants the paged responses to be simplified to a generator hiding the token handling and batched queries to use in loops.

Describe the solution you'd like

class Gmail(Consumer):
    @paging(request_token = Query("pageToken"), init_value = None, response_token = "nextPageToken", response_data = "messages")
    @get("users/{userId}/messages")
    def get_user_messages(self, user_id: Path("userId"), ...) -> Iterator[Message]:
        """Lists the messages in the user's mailbox."""

Additional context
Several variants of paging exists based on the location of the page token and location of the underlying iterator data.

[chaoshui66]

While I appreciate the suggestion for a @paging decorator, I believe pagination handling should remain outside of uplink's scope. Different APIs implement pagination in various ways (token-based, offset/limit, cursor-based), and developers often need custom control over pagination logic. A simple generator function in the application code would be more flexible and maintainable than building this into the framework itself.

[asdkant-bf]

While I appreciate the suggestion for a @paging decorator, I believe pagination handling should remain outside of uplink's scope. Different APIs implement pagination in various ways (token-based, offset/limit, cursor-based), and developers often need custom control over pagination logic. A simple generator function in the application code would be more flexible and maintainable than building this into the framework itself.

There are some very common paging mechanisms which could be supported in uplink, and anything different can be implemented by hand as it is being done now.