Proposal: API spec for paginated version of getAlertGroups and getAlerts

Background

Without pagination of the APIs, the getAlertGroups and getAlerts can cause a significant performance impact on the server
After discussed in proposal, we get an agreement on create a brand new API to return only alert group information.
This proposal will discuss the API spec of the paginated version of getAlertGroups and getAlerts

getAlertGroupsInfo

• URL query parameters:
  • maxResults Integer. The maximum number of alert groups to return in one getAlertGroupsInfo operation. The range is 1–1000. Optional
  • nextToken String. The token for the next set of items to return. (You received this token from a previous call.). Optional
  • filter An array of strings. A list of matchers to filter alert group by. Optional
  • receiver String. A regular expression matching receivers to filter alerts by. Optional
• Sample response

      groups: [
      {
          "labels": {
              "group": "hello1"
          },
          "receiver": {
              "name": "example-sns"
          },
          "route": "{ROUTE_UUID}"
      },
      {
          "labels": {
              "group": "hello2"
          },
          "receiver": {
              "name": "example-sns"
          }, 
          "fingerprint": "{group_UUID}"
      }
      ],
        nextToken:"123"

getAlerts

• URL query parameters:
  • maxResults Integer. The maximum number of alerts to return in one getAlerts operation. The range is 1–1000. Optional
  • nextToken String. The token for the next set of items to return. (You received this token from a previous call.). Optional
  • active Boolean. If true, the returned list includes active alerts. The default is true. Optional
  • silenced Boolean. If true, the returned list includes silenced alerts. The default is true. Optional
  • inhibited Boolean. If true, the returned list includes inhibited alerts. The default is true. Optional
  • unprocessed Boolean. If true, the returned list includes unprocessed alerts. The default is true. Optional
  • filter An array of strings. A list of matchers to filter alerts by. Optional
  • receiver String. A regular expression matching receivers to filter alerts by. Optional
  • groupId String. The group id to filter alerts by. Optional
• Sample response

{
  "alerts": [
    {
      "annotations": {
        "summary": "this is a test alert used for demo purposes"
      },
      "endsAt": "2021-10-21T22:07:31.501Z",
      "fingerprint": "375eab7b59892505",
      "receivers": [
        {
          "name": "sns-0"
        }
      ],
      "startsAt": "2021-10-21T22:02:31.501Z",
      "status": {
        "inhibitedBy": [],
        "silencedBy": [],
        "state": "active"
      },
      "updatedAt": "2021-10-21T22:02:31.501Z",
      "labels": {
        "alertname": "test-alert"
      }
    }
  ],
  "nextToken": "123"
}

other consideration

Add UUID for each route

For current data structure, one route can not be unique identified by receiver name.
However in order to search the alerts by alert group we need a fingerprint to identify the referenced alert group. The finger print to unique identify the alerting group should be group labels + route info.
We proposed to generate a unique identifier to each route as it is created

Add group information for each alert in the response of getAlerts API

It will be a better user experience if we can link the alerts back to the alert groups.
We proposed to add the groups info for each alert to the response of getAlerts API

Review api/v2/openapi.yaml and the linked proposal in issue #3297 first, then compare the existing getAlertGroups and getAlerts definitions with the proposed parameters and responses. Done means the paginated API specification, including nextToken handling and the proposed alert-group linkage, is agreed and documented consistently.