add docs for pagination in /api/v2/metrics endpoint

.apigentools-info

@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2024-12-11 20:35:38.546745",
-            "spec_repo_commit": "7b62d196"
+            "regenerated": "2024-12-12 13:29:22.125167",
+            "spec_repo_commit": "f0c3c0f4"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2024-12-11 20:35:38.566354",
-            "spec_repo_commit": "7b62d196"
+            "regenerated": "2024-12-12 13:29:22.145471",
+            "spec_repo_commit": "f0c3c0f4"
         }
     }
 }

.generator/schemas/v2/openapi.yaml

@@ -16012,6 +16012,36 @@ components:
       - COUNT
       - RATE
       - GAUGE
+    MetricMetaPage:
+      description: Paging attributes. Only present if pagination query parameters
+        were provided.
+      properties:
+        cursor:
+          description: The cursor used to get the current results, if any.
+          nullable: true
+          type: string
+        limit:
+          description: Number of results returned
+          format: int32
+          maximum: 20000
+          minimum: 0
+          type: integer
+        next_cursor:
+          description: The cursor used to get the next results, if any.
+          nullable: true
+          type: string
+        type:
+          $ref: '#/components/schemas/MetricMetaPageType'
+      type: object
+    MetricMetaPageType:
+      default: cursor_limit
+      description: Type of metric pagination.
+      enum:
+      - cursor_limit
+      example: cursor_limit
+      type: string
+      x-enum-varnames:
+      - CURSOR_LIMIT
     MetricMetadata:
       description: Metadata for the metric.
       properties:
@@ -16094,6 +16124,12 @@ components:
           maximum: 1000
           type: integer
       type: object
+    MetricPaginationMeta:
+      description: Response metadata object.
+      properties:
+        pagination:
+          $ref: '#/components/schemas/MetricMetaPage'
+      type: object
     MetricPayload:
       description: The metrics' payload.
       properties:
@@ -16570,6 +16606,10 @@ components:
           items:
             $ref: '#/components/schemas/MetricsAndMetricTagConfigurations'
           type: array
+        links:
+          $ref: '#/components/schemas/MetricsListResponseLinks'
+        meta:
+          $ref: '#/components/schemas/MetricPaginationMeta'
       readOnly: true
       type: object
     MetricsDataSource:
@@ -16583,6 +16623,29 @@ components:
       x-enum-varnames:
       - METRICS
       - CLOUD_COST
+    MetricsListResponseLinks:
+      description: Pagination links. Only present if pagination query parameters were
+        provided.
+      properties:
+        first:
+          description: Link to the first page.
+          type: string
+        last:
+          description: Link to the last page.
+          nullable: true
+          type: string
+        next:
+          description: Link to the next page.
+          nullable: true
+          type: string
+        prev:
+          description: Link to previous page.
+          nullable: true
+          type: string
+        self:
+          description: Link to current page.
+          type: string
+      type: object
     MetricsScalarQuery:
       description: An individual scalar metrics query.
       properties:
@@ -35773,7 +35836,12 @@ paths:
     get:
       description: "Returns all metrics that can be configured in the Metrics Summary
         page or with Metrics without Limits\u2122 (matching additional filters if
-        specified)."
+        specified).\nOptionally, paginate by using the `page[cursor]` and/or `page[size]`
+        query parameters.\nTo fetch the first page, pass in a query parameter with
+        either a valid `page[size]` or an empty cursor like `page[cursor]=`. To fetch
+        the next page, pass in the `next_cursor` value from the response as the new
+        `page[cursor]` value.\nOnce the `meta.pagination.next_cursor` value is null,
+        all pages have been retrieved."
       operationId: ListTagConfigurations
       parameters:
       - description: Filter custom metrics that have configured tags.
@@ -35838,6 +35906,27 @@ paths:
         schema:
           format: int64
           type: integer
+      - description: Maximum number of results returned.
+        in: query
+        name: page[size]
+        required: false
+        schema:
+          default: 10000
+          format: int32
+          maximum: 10000
+          minimum: 1
+          type: integer
+      - description: 'String to query the next page of results.
+
+          This key is provided with each valid response from the API in `meta.pagination.next_cursor`.
+
+          Once the `meta.pagination.next_cursor` key is null, all pages have been
+          retrieved.'
+        in: query
+        name: page[cursor]
+        required: false
+        schema:
+          type: string
       responses:
         '200':
           content:
@@ -35871,6 +35960,11 @@ paths:
       summary: Get a list of metrics
       tags:
       - Metrics
+      x-pagination:
+        cursorParam: page[cursor]
+        cursorPath: meta.pagination.next_cursor
+        limitParam: page[size]
+        resultsPath: data
       x-permission:
         operator: OR
         permissions:

examples/v2/metrics/ListTagConfigurations_3969783727.java

@@ -0,0 +1,28 @@
+// Get a list of metrics returns "Success" response with pagination
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.PaginationIterable;
+import com.datadog.api.client.v2.api.MetricsApi;
+import com.datadog.api.client.v2.api.MetricsApi.ListTagConfigurationsOptionalParameters;
+import com.datadog.api.client.v2.model.MetricsAndMetricTagConfigurations;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    MetricsApi apiInstance = new MetricsApi(defaultClient);
+
+    try {
+      PaginationIterable<MetricsAndMetricTagConfigurations> iterable =
+          apiInstance.listTagConfigurationsWithPagination(
+              new ListTagConfigurationsOptionalParameters().pageSize(2));
+
+      for (MetricsAndMetricTagConfigurations item : iterable) {
+        System.out.println(item);
+      }
+    } catch (RuntimeException e) {
+      System.err.println("Exception when calling MetricsApi#listTagConfigurationsWithPagination");
+      System.err.println("Reason: " + e.getMessage());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/v2/api/MetricsApi.java

@@ -3,6 +3,7 @@
 import com.datadog.api.client.ApiClient;
 import com.datadog.api.client.ApiException;
 import com.datadog.api.client.ApiResponse;
+import com.datadog.api.client.PaginationIterable;
 import com.datadog.api.client.Pair;
 import com.datadog.api.client.v2.model.IntakePayloadAccepted;
 import com.datadog.api.client.v2.model.MetricAllTagsResponse;
@@ -19,6 +20,7 @@
 import com.datadog.api.client.v2.model.MetricTagConfigurationResponse;
 import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateRequest;
 import com.datadog.api.client.v2.model.MetricVolumesResponse;
+import com.datadog.api.client.v2.model.MetricsAndMetricTagConfigurations;
 import com.datadog.api.client.v2.model.MetricsAndMetricTagConfigurationsResponse;
 import com.datadog.api.client.v2.model.ScalarFormulaQueryRequest;
 import com.datadog.api.client.v2.model.ScalarFormulaQueryResponse;
@@ -28,6 +30,7 @@
 import jakarta.ws.rs.core.GenericType;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
@@ -1450,6 +1453,8 @@ public static class ListTagConfigurationsOptionalParameters {
     private Boolean filterQueried;
     private String filterTags;
     private Long windowSeconds;
+    private Integer pageSize;
+    private String pageCursor;
 
     /**
      * Set filterConfigured.
@@ -1537,6 +1542,30 @@ public ListTagConfigurationsOptionalParameters windowSeconds(Long windowSeconds)
       this.windowSeconds = windowSeconds;
       return this;
     }
+
+    /**
+     * Set pageSize.
+     *
+     * @param pageSize Maximum number of results returned. (optional, default to 10000)
+     * @return ListTagConfigurationsOptionalParameters
+     */
+    public ListTagConfigurationsOptionalParameters pageSize(Integer pageSize) {
+      this.pageSize = pageSize;
+      return this;
+    }
+
+    /**
+     * Set pageCursor.
+     *
+     * @param pageCursor String to query the next page of results. This key is provided with each
+     *     valid response from the API in <code>meta.pagination.next_cursor</code>. Once the <code>
+     *     meta.pagination.next_cursor</code> key is null, all pages have been retrieved. (optional)
+     * @return ListTagConfigurationsOptionalParameters
+     */
+    public ListTagConfigurationsOptionalParameters pageCursor(String pageCursor) {
+      this.pageCursor = pageCursor;
+      return this;
+    }
   }
 
   /**
@@ -1598,9 +1627,68 @@ public CompletableFuture<MetricsAndMetricTagConfigurationsResponse> listTagConfi
             });
   }
 
+  /**
+   * Get a list of metrics.
+   *
+   * <p>See {@link #listTagConfigurationsWithHttpInfo}.
+   *
+   * @return PaginationIterable&lt;MetricsAndMetricTagConfigurations&gt;
+   */
+  public PaginationIterable<MetricsAndMetricTagConfigurations>
+      listTagConfigurationsWithPagination() {
+    ListTagConfigurationsOptionalParameters parameters =
+        new ListTagConfigurationsOptionalParameters();
+    return listTagConfigurationsWithPagination(parameters);
+  }
+
+  /**
+   * Get a list of metrics.
+   *
+   * <p>See {@link #listTagConfigurationsWithHttpInfo}.
+   *
+   * @return MetricsAndMetricTagConfigurationsResponse
+   */
+  public PaginationIterable<MetricsAndMetricTagConfigurations> listTagConfigurationsWithPagination(
+      ListTagConfigurationsOptionalParameters parameters) {
+    String resultsPath = "getData";
+    String valueGetterPath = "getMeta.getPagination.getNextCursor";
+    String valueSetterPath = "pageCursor";
+    Boolean valueSetterParamOptional = true;
+    Integer limit;
+
+    if (parameters.pageSize == null) {
+      limit = 10000;
+      parameters.pageSize(limit);
+    } else {
+      limit = parameters.pageSize;
+    }
+
+    LinkedHashMap<String, Object> args = new LinkedHashMap<String, Object>();
+    args.put("optionalParams", parameters);
+
+    PaginationIterable iterator =
+        new PaginationIterable(
+            this,
+            "listTagConfigurations",
+            resultsPath,
+            valueGetterPath,
+            valueSetterPath,
+            valueSetterParamOptional,
+            true,
+            limit,
+            args);
+
+    return iterator;
+  }
+
   /**
    * Returns all metrics that can be configured in the Metrics Summary page or with Metrics without
-   * Limits™ (matching additional filters if specified).
+   * Limits™ (matching additional filters if specified). Optionally, paginate by using the <code>
+   * page[cursor]</code> and/or <code>page[size]</code> query parameters. To fetch the first page,
+   * pass in a query parameter with either a valid <code>page[size]</code> or an empty cursor like
+   * <code>page[cursor]=</code>. To fetch the next page, pass in the <code>next_cursor</code> value
+   * from the response as the new <code>page[cursor]</code> value. Once the <code>
+   * meta.pagination.next_cursor</code> value is null, all pages have been retrieved.
    *
    * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;MetricsAndMetricTagConfigurationsResponse&gt;
@@ -1625,6 +1713,8 @@ public ApiResponse<MetricsAndMetricTagConfigurationsResponse> listTagConfigurati
     Boolean filterQueried = parameters.filterQueried;
     String filterTags = parameters.filterTags;
     Long windowSeconds = parameters.windowSeconds;
+    Integer pageSize = parameters.pageSize;
+    String pageCursor = parameters.pageCursor;
     // create path and map variables
     String localVarPath = "/api/v2/metrics";
 
@@ -1642,6 +1732,8 @@ public ApiResponse<MetricsAndMetricTagConfigurationsResponse> listTagConfigurati
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[queried]", filterQueried));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[tags]", filterTags));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "window[seconds]", windowSeconds));
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[size]", pageSize));
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[cursor]", pageCursor));
 
     Invocation.Builder builder =
         apiClient.createBuilder(
@@ -1681,6 +1773,8 @@ public ApiResponse<MetricsAndMetricTagConfigurationsResponse> listTagConfigurati
     Boolean filterQueried = parameters.filterQueried;
     String filterTags = parameters.filterTags;
     Long windowSeconds = parameters.windowSeconds;
+    Integer pageSize = parameters.pageSize;
+    String pageCursor = parameters.pageCursor;
     // create path and map variables
     String localVarPath = "/api/v2/metrics";
 
@@ -1698,6 +1792,8 @@ public ApiResponse<MetricsAndMetricTagConfigurationsResponse> listTagConfigurati
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[queried]", filterQueried));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[tags]", filterTags));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "window[seconds]", windowSeconds));
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[size]", pageSize));
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "page[cursor]", pageCursor));
 
     Invocation.Builder builder;
     try {