Guidance on pagination token

This issue is for discuss how we should implement the pagination token for https://github.com/prometheus/alertmanager/issues/3361. Open this issue to bring a discussion on best practices for pagination tokens with open-source guidance.

Background

Without pagination of the APIs, the getAlertGroups and getAlerts can cause a significant performance impact on the server.
We had discussed in https://github.com/prometheus/alertmanager/issues/3297 and agreed on to have a set of new APIs to support pagination token

Implementation requirements for pagination token

Pagination tokens should not be plain text

In order to not expose pagination tokens implementation details, we should not use plain text for pagination token. Proposed to use base64 to encode the token to start

Pagination tokens should not be versioned

To be able to not break in flight request while deploying new version of pagination token, we should make sure that the pagination token is versioned

Other consideration

• Pagination tokens should require filter parameter remain unchanged: In order to validate the filter parameters, we'll need to encode the initial filter parameter into the response pagination token. However, considering that we support numerous filter parameters, many of which support list operations, encoding all this information could result in very long pagination tokens. Therefore, I suggest postponing this requirement.

Start with issue 3361 and the getAlertGroups and getAlerts definitions in the linked Alertmanager API specification. Review the pagination-token requirements and open questions, then document an agreed design and its compatibility and filtering behavior.