add docs for pagination in /api/v2/metrics endpoint (#2021)

Co-authored-by: ci.datadog-api-spec <[email protected]>

Author: api-clients-generation-pipeline[bot]

.apigentools-info

@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2024-12-11 20:35:37.297873",
-            "spec_repo_commit": "7b62d196"
+            "regenerated": "2024-12-12 13:29:22.131222",
+            "spec_repo_commit": "f0c3c0f4"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2024-12-11 20:35:37.316642",
-            "spec_repo_commit": "7b62d196"
+            "regenerated": "2024-12-12 13:29:22.150037",
+            "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:

cassettes/features/v2/metrics/Get-a-list-of-metrics-returns-Success-response-with-pagination.frozen

@@ -0,0 +1 @@
+2024-12-06T19:12:25.667Z

cassettes/features/v2/metrics/Get-a-list-of-metrics-returns-Success-response-with-pagination.yml

@@ -0,0 +1,8 @@
+# Get a list of metrics returns "Success" response with pagination
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V2::MetricsAPI.new
+opts = {
+  page_size: 2,
+}
+api_instance.list_tag_configurations_with_pagination(opts) { |item| puts item }

examples/v2/metrics/ListTagConfigurations_3969783727.rb

@@ -1582,6 +1582,8 @@
             "filter_queried" => "Boolean",
             "filter_tags" => "String",
             "window_seconds" => "Integer",
+            "page_size" => "Integer",
+            "page_cursor" => "String",
     },
     "v2.DeleteBulkTagsMetricsConfiguration" => {
             "body" => "MetricBulkTagConfigDeleteRequest",

features/scenarios_model_mapping.rb

@@ -125,6 +125,15 @@ Feature: Metrics
     When the request is sent
     Then the response status is 200 Success
 
+  @replay-only @skip-validation @team:DataDog/metrics-experience @with-pagination
+  Scenario: Get a list of metrics returns "Success" response with pagination
+    Given a valid "appKeyAuth" key in the system
+    And new "ListTagConfigurations" request
+    And request contains "page[size]" parameter with value 2
+    When the request with pagination is sent
+    Then the response status is 200 Success
+    And the response has 3 items
+
   @team:DataDog/metrics-experience
   Scenario: Get a list of metrics with a tag filter returns "Success" response
     Given a valid "appKeyAuth" key in the system

features/v2/metrics.feature

@@ -1868,11 +1868,14 @@ def overrides
           "v2.metric_ingested_indexed_volume_type" => "MetricIngestedIndexedVolumeType",
           "v2.metric_intake_type" => "MetricIntakeType",
           "v2.metric_metadata" => "MetricMetadata",
+          "v2.metric_meta_page" => "MetricMetaPage",
+          "v2.metric_meta_page_type" => "MetricMetaPageType",
           "v2.metric_monitor_asset" => "MetricMonitorAsset",
           "v2.metric_monitor_type" => "MetricMonitorType",
           "v2.metric_notebook_asset" => "MetricNotebookAsset",
           "v2.metric_notebook_type" => "MetricNotebookType",
           "v2.metric_origin" => "MetricOrigin",
+          "v2.metric_pagination_meta" => "MetricPaginationMeta",
           "v2.metric_payload" => "MetricPayload",
           "v2.metric_point" => "MetricPoint",
           "v2.metric_resource" => "MetricResource",
@@ -1881,6 +1884,7 @@ def overrides
           "v2.metrics_and_metric_tag_configurations_response" => "MetricsAndMetricTagConfigurationsResponse",
           "v2.metrics_data_source" => "MetricsDataSource",
           "v2.metric_series" => "MetricSeries",
+          "v2.metrics_list_response_links" => "MetricsListResponseLinks",
           "v2.metric_slo_asset" => "MetricSLOAsset",
           "v2.metric_slo_type" => "MetricSLOType",
           "v2.metrics_scalar_query" => "MetricsScalarQuery",

lib/datadog_api_client/inflector.rb

@@ -603,6 +603,9 @@ def list_tag_configurations(opts = {})
     # Get a list of metrics.
     #
     # Returns all metrics that can be configured in the Metrics Summary page or with Metrics without Limits™ (matching additional filters if specified).
+    # Optionally, paginate by using the `page[cursor]` and/or `page[size]` query parameters.
+    # To 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.
+    # Once the `meta.pagination.next_cursor` value is null, all pages have been retrieved.
     #
     # @param opts [Hash] the optional parameters
     # @option opts [Boolean] :filter_configured Filter custom metrics that have configured tags.
@@ -612,6 +615,8 @@ def list_tag_configurations(opts = {})
     # @option opts [Boolean] :filter_queried (Beta) Filter custom metrics that have or have not been queried in the specified window[seconds]. If no window is provided or the window is less than 2 hours, a default of 2 hours will be applied.
     # @option opts [String] :filter_tags Filter metrics that have been submitted with the given tags. Supports boolean and wildcard expressions. Can only be combined with the filter[queried] filter.
     # @option opts [Integer] :window_seconds The number of seconds of look back (from now) to apply to a filter[tag] or filter[queried] query. Default value is 3600 (1 hour), maximum value is 2,592,000 (30 days).
+    # @option opts [Integer] :page_size Maximum number of results returned.
+    # @option opts [String] :page_cursor 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.
     # @return [Array<(MetricsAndMetricTagConfigurationsResponse, Integer, Hash)>] MetricsAndMetricTagConfigurationsResponse data, response status code and response headers
     def list_tag_configurations_with_http_info(opts = {})
 
@@ -622,6 +627,12 @@ def list_tag_configurations_with_http_info(opts = {})
       if @api_client.config.client_side_validation && opts[:'filter_metric_type'] && !allowable_values.include?(opts[:'filter_metric_type'])
         fail ArgumentError, "invalid value for \"filter_metric_type\", must be one of #{allowable_values}"
       end
+      if @api_client.config.client_side_validation && !opts[:'page_size'].nil? && opts[:'page_size'] > 10000
+        fail ArgumentError, 'invalid value for "opts[:"page_size"]" when calling MetricsAPI.list_tag_configurations, must be smaller than or equal to 10000.'
+      end
+      if @api_client.config.client_side_validation && !opts[:'page_size'].nil? && opts[:'page_size'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"page_size"]" when calling MetricsAPI.list_tag_configurations, must be greater than or equal to 1.'
+      end
       # resource path
       local_var_path = '/api/v2/metrics'
 
@@ -634,6 +645,8 @@ def list_tag_configurations_with_http_info(opts = {})
       query_params[:'filter[queried]'] = opts[:'filter_queried'] if !opts[:'filter_queried'].nil?
       query_params[:'filter[tags]'] = opts[:'filter_tags'] if !opts[:'filter_tags'].nil?
       query_params[:'window[seconds]'] = opts[:'window_seconds'] if !opts[:'window_seconds'].nil?
+      query_params[:'page[size]'] = opts[:'page_size'] if !opts[:'page_size'].nil?
+      query_params[:'page[cursor]'] = opts[:'page_cursor'] if !opts[:'page_cursor'].nil?
 
       # header parameters
       header_params = opts[:header_params] || {}
@@ -670,6 +683,27 @@ def list_tag_configurations_with_http_info(opts = {})
       return data, status_code, headers
     end
 
+    # Get a list of metrics.
+    #
+    # Provide a paginated version of {#list_tag_configurations}, returning all items.
+    #
+    # To use it you need to use a block: list_tag_configurations_with_pagination { |item| p item }
+    #
+    # @yield [MetricsAndMetricTagConfigurations] Paginated items
+    def list_tag_configurations_with_pagination(opts = {})
+        api_version = "V2"
+        page_size = @api_client.get_attribute_from_path(opts, "page_size", 10000)
+        @api_client.set_attribute_from_path(api_version, opts, "page_size", Integer, page_size)
+        while true do
+            response = list_tag_configurations(opts)
+            @api_client.get_attribute_from_path(response, "data").each { |item| yield(item) }
+            if @api_client.get_attribute_from_path(response, "data").length < page_size
+              break
+            end
+            @api_client.set_attribute_from_path(api_version, opts, "page_cursor", String, @api_client.get_attribute_from_path(response, "meta.pagination.next_cursor"))
+        end
+    end
+
     # List tags by metric name.
     #
     # @see #list_tags_by_metric_name_with_http_info