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

Co-authored-by: Sherzod Karimov <sherzod.karimov@datadoghq.com>
Co-authored-by: api-clients-generation-pipeline[bot] <54105614+api-clients-generation-pipeline[bot]@users.noreply.github.com>
Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

.apigentools-info

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

.generator/src/generator/templates/api.j2

@@ -256,12 +256,13 @@ impl {{ structName }} {
                 {%- set cursorPathParts = pagination.cursorPath.split(".") %}
                 {%- for i in range(cursorPathParts|length) %}
                 {%- set ns.required = cursorPathParts[i] in ns.parentSchema.get("required", []) %}
+                {%- set ns.nullable = ns.parentSchema.properties[cursorPathParts[i]].get("nullable", False) %}
 
                 {%- if ns.required %}
                 {%- set ns.cursorGetter = ns.cursorGetter ~ "." ~ cursorPathParts[i] %}
                 {%- else %}
                 {%- set attrName = cursorPathParts[i]|variable_name %}
-                let Some({{ attrName }}) = {{ ns.cursorGetter }}.{{ attrName }} else { break };
+                let Some({{ attrName }}) = {{ ns.cursorGetter }}.{{ attrName }}{%if ns.nullable %}.unwrap(){% endif %} else { break };
                 {%- set ns.cursorGetter = attrName %}
                 {%- endif %}
 

examples/v2_metrics_ListTagConfigurations_3969783727.rs

@@ -0,0 +1,23 @@
+// Get a list of metrics returns "Success" response with pagination
+use datadog_api_client::datadog;
+use datadog_api_client::datadogV2::api_metrics::ListTagConfigurationsOptionalParams;
+use datadog_api_client::datadogV2::api_metrics::MetricsAPI;
+use futures_util::pin_mut;
+use futures_util::stream::StreamExt;
+
+#[tokio::main]
+async fn main() {
+    let configuration = datadog::Configuration::new();
+    let api = MetricsAPI::with_config(configuration);
+    let response = api.list_tag_configurations_with_pagination(
+        ListTagConfigurationsOptionalParams::default().page_size(2),
+    );
+    pin_mut!(response);
+    while let Some(resp) = response.next().await {
+        if let Ok(value) = resp {
+            println!("{:#?}", value);
+        } else {
+            println!("{:#?}", resp.unwrap_err());
+        }
+    }
+}

src/datadogV2/api/api_metrics.rs

@@ -2,10 +2,12 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2019-Present Datadog, Inc.
 use crate::datadog;
+use async_stream::try_stream;
 use flate2::{
     write::{GzEncoder, ZlibEncoder},
     Compression,
 };
+use futures_core::stream::Stream;
 use reqwest::header::{HeaderMap, HeaderValue};
 use serde::{Deserialize, Serialize};
 use std::io::Write;
@@ -95,6 +97,12 @@ pub struct ListTagConfigurationsOptionalParams {
     /// 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).
     pub window_seconds: Option<i64>,
+    /// Maximum number of results returned.
+    pub page_size: Option<i32>,
+    /// 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.
+    pub page_cursor: Option<String>,
 }
 
 impl ListTagConfigurationsOptionalParams {
@@ -140,6 +148,18 @@ impl ListTagConfigurationsOptionalParams {
         self.window_seconds = Some(value);
         self
     }
+    /// Maximum number of results returned.
+    pub fn page_size(mut self, value: i32) -> Self {
+        self.page_size = Some(value);
+        self
+    }
+    /// 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.
+    pub fn page_cursor(mut self, value: String) -> Self {
+        self.page_cursor = Some(value);
+        self
+    }
 }
 
 /// SubmitMetricsOptionalParams is a struct for passing parameters to the method [`MetricsAPI::submit_metrics`]
@@ -1440,6 +1460,9 @@ impl MetricsAPI {
     }
 
     /// 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.
     pub async fn list_tag_configurations(
         &self,
         params: ListTagConfigurationsOptionalParams,
@@ -1461,7 +1484,48 @@ impl MetricsAPI {
         }
     }
 
+    pub fn list_tag_configurations_with_pagination(
+        &self,
+        mut params: ListTagConfigurationsOptionalParams,
+    ) -> impl Stream<
+        Item = Result<
+            crate::datadogV2::model::MetricsAndMetricTagConfigurations,
+            datadog::Error<ListTagConfigurationsError>,
+        >,
+    > + '_ {
+        try_stream! {
+            let mut page_size: i32 = 10000;
+            if params.page_size.is_none() {
+                params.page_size = Some(page_size);
+            } else {
+                page_size = params.page_size.unwrap().clone();
+            }
+            loop {
+                let resp = self.list_tag_configurations(params.clone()).await?;
+                let Some(data) = resp.data else { break };
+
+                let r = data;
+                let count = r.len();
+                for team in r {
+                    yield team;
+                }
+
+                if count < page_size as usize {
+                    break;
+                }
+                let Some(meta) = resp.meta else { break };
+                let Some(pagination) = meta.pagination else { break };
+                let Some(next_cursor) = pagination.next_cursor.unwrap() else { break };
+
+                params.page_cursor = Some(next_cursor);
+            }
+        }
+    }
+
     /// 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.
     pub async fn list_tag_configurations_with_http_info(
         &self,
         params: ListTagConfigurationsOptionalParams,
@@ -1482,6 +1546,8 @@ impl MetricsAPI {
         let filter_queried = params.filter_queried;
         let filter_tags = params.filter_tags;
         let window_seconds = params.window_seconds;
+        let page_size = params.page_size;
+        let page_cursor = params.page_cursor;
 
         let local_client = &self.client;
 
@@ -1522,6 +1588,14 @@ impl MetricsAPI {
             local_req_builder =
                 local_req_builder.query(&[("window[seconds]", &local_query_param.to_string())]);
         };
+        if let Some(ref local_query_param) = page_size {
+            local_req_builder =
+                local_req_builder.query(&[("page[size]", &local_query_param.to_string())]);
+        };
+        if let Some(ref local_query_param) = page_cursor {
+            local_req_builder =
+                local_req_builder.query(&[("page[cursor]", &local_query_param.to_string())]);
+        };
 
         // build headers
         let mut headers = HeaderMap::new();

src/datadogV2/model/mod.rs

@@ -1908,6 +1908,14 @@ pub mod model_metric_tag_configuration_type;
 pub use self::model_metric_tag_configuration_type::MetricTagConfigurationType;
 pub mod model_metrics_and_metric_tag_configurations;
 pub use self::model_metrics_and_metric_tag_configurations::MetricsAndMetricTagConfigurations;
+pub mod model_metrics_list_response_links;
+pub use self::model_metrics_list_response_links::MetricsListResponseLinks;
+pub mod model_metric_pagination_meta;
+pub use self::model_metric_pagination_meta::MetricPaginationMeta;
+pub mod model_metric_meta_page;
+pub use self::model_metric_meta_page::MetricMetaPage;
+pub mod model_metric_meta_page_type;
+pub use self::model_metric_meta_page_type::MetricMetaPageType;
 pub mod model_metric_bulk_tag_config_delete_request;
 pub use self::model_metric_bulk_tag_config_delete_request::MetricBulkTagConfigDeleteRequest;
 pub mod model_metric_bulk_tag_config_delete;