Add dashboard widget validation API

.generator/schemas/v2/openapi.yaml

@@ -30853,6 +30853,94 @@ components:
           example: Jane Doe
           type: string
       type: object
+    DashboardWidgetValidationLayoutType:
+      description: Layout type used to apply dashboard-specific widget layout validation.
+      enum:
+        - ordered
+        - free
+      example: ordered
+      type: string
+      x-enum-varnames:
+        - ORDERED
+        - FREE
+    DashboardWidgetValidationReflowType:
+      description: Reflow behavior used for an ordered dashboard.
+      enum:
+        - auto
+        - fixed
+      example: auto
+      type: string
+      x-enum-varnames:
+        - AUTO
+        - FIXED
+    DashboardWidgetValidationRequest:
+      description: Request containing dashboard widgets and their layout context.
+      properties:
+        layout_type:
+          $ref: "#/components/schemas/DashboardWidgetValidationLayoutType"
+        reflow_type:
+          $ref: "#/components/schemas/DashboardWidgetValidationReflowType"
+          nullable: true
+        widgets:
+          description: Dashboard widgets to validate.
+          example:
+            - definition:
+                content: Valid note
+                type: note
+          items:
+            $ref: "#/components/schemas/DashboardWidgetValidationWidget"
+          type: array
+      required:
+        - widgets
+        - layout_type
+      type: object
+    DashboardWidgetValidationResponse:
+      description: Ordered validation results corresponding to the requested widgets.
+      properties:
+        results:
+          description: Validation results in the same order as the requested widgets.
+          items:
+            $ref: "#/components/schemas/DashboardWidgetValidationResult"
+          type: array
+      required:
+        - results
+      type: object
+    DashboardWidgetValidationResult:
+      description: Validation result for one dashboard widget.
+      properties:
+        error_message:
+          description: Validation error message, when the widget is invalid.
+          example: Invalid widget definition at position `0` of type `timeseries`.
+          nullable: true
+          type: string
+        error_path:
+          description: Path to the invalid value, when available.
+          example: "['requests', 0, 'display_type']"
+          nullable: true
+          type: string
+        is_valid:
+          description: Whether the widget passed validation.
+          example: false
+          type: boolean
+        widget_type:
+          description: Type of the validated widget, when available.
+          example: timeseries
+          nullable: true
+          type: string
+      required:
+        - is_valid
+        - widget_type
+        - error_message
+        - error_path
+      type: object
+    DashboardWidgetValidationWidget:
+      additionalProperties: {}
+      description: A dashboard widget to validate.
+      example:
+        definition:
+          content: Valid note
+          type: note
+      type: object
     DataAttributesRulesItemsIfTagExists:
       description: The behavior when the tag already exists.
       enum:
@@ -138616,6 +138704,78 @@ paths:
       tags:
         - Dashboard Lists
       x-codegen-request-body-name: body
+  /api/v2/dashboard/widgets/validate:
+    post:
+      description: Validate dashboard widgets without creating or updating a dashboard.
+      operationId: ValidateDashboardWidgets
+      requestBody:
+        content:
+          application/json:
+            examples:
+              default:
+                value:
+                  layout_type: ordered
+                  widgets:
+                    - definition:
+                        content: Valid note
+                        type: note
+            schema:
+              $ref: "#/components/schemas/DashboardWidgetValidationRequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                default:
+                  value:
+                    results:
+                      - error_message:
+                        error_path:
+                        is_valid: true
+                        widget_type: note
+              schema:
+                $ref: "#/components/schemas/DashboardWidgetValidationResponse"
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/APIErrorResponse"
+          description: Bad Request
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/APIErrorResponse"
+          description: Forbidden
+        "422":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/APIErrorResponse"
+          description: Unprocessable Entity
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - dashboards_read
+        - AuthZ:
+            - dashboards_write
+      summary: Validate dashboard widgets
+      tags:
+        - Dashboards
+      x-codegen-request-body-name: body
+      x-permission:
+        operator: OR
+        permissions:
+          - dashboards_read
+          - dashboards_write
+      x-unstable: |-
+        **Note**: This endpoint is in Preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/dashboard/{dashboard_id}/shared:
     get:
       description: Retrieve shared dashboards associated with the specified dashboard.

examples/v2/dashboards/ValidateDashboardWidgets.rb

@@ -0,0 +1,16 @@
+# Validate dashboard widgets returns "OK" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.validate_dashboard_widgets".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::DashboardsAPI.new
+
+body = DatadogAPIClient::V2::DashboardWidgetValidationRequest.new({
+  layout_type: DatadogAPIClient::V2::DashboardWidgetValidationLayoutType::ORDERED,
+  reflow_type: DatadogAPIClient::V2::DashboardWidgetValidationReflowType::AUTO,
+  widgets: [
+    DatadogAPIClient::V2::DashboardWidgetValidationWidget.new({}),
+  ],
+})
+p api_instance.validate_dashboard_widgets(body)

features/scenarios_model_mapping.rb

@@ -3103,6 +3103,18 @@
             "dashboard_list_id" => "Integer",
             "body" => "DashboardListUpdateItemsRequest",
     },
+    "v2.ValidateDashboardWidgets" => {
+            "body" => "DashboardWidgetValidationRequest",
+    },
+    "v2.ListDashboardsUsage" => {
+            "page_limit" => "Integer",
+            "page_offset" => "Integer",
+            "filter_edited_before" => "String",
+            "filter_viewed_before" => "String",
+    },
+    "v2.GetDashboardUsage" => {
+            "dashboard_id" => "String",
+    },
     "v2.ListSharedDashboardsByDashboardId" => {
             "dashboard_id" => "String",
     },
@@ -3123,15 +3135,6 @@
             "token" => "String",
             "body" => "SecureEmbedUpdateRequest",
     },
-    "v2.ListDashboardsUsage" => {
-            "page_limit" => "Integer",
-            "page_offset" => "Integer",
-            "filter_edited_before" => "String",
-            "filter_viewed_before" => "String",
-    },
-    "v2.GetDashboardUsage" => {
-            "dashboard_id" => "String",
-    },
     "v2.GetDataObservabilityMonitorRunStatus" => {
             "run_id" => "String",
     },

features/v2/dashboards.feature

@@ -99,3 +99,32 @@ Feature: Dashboards
     When the request is sent
     Then the response status is 200 OK
     And the response "meta.page" has field "total"
+
+  @generated @skip @team:DataDog/dashboards-backend
+  Scenario: Validate dashboard widgets returns "Bad Request" response
+    Given operation "ValidateDashboardWidgets" enabled
+    And new "ValidateDashboardWidgets" request
+    And body with value {"layout_type": "ordered", "reflow_type": "auto", "widgets": [{"definition": {"content": "Valid note", "type": "note"}}]}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @team:DataDog/dashboards-backend
+  Scenario: Validate dashboard widgets returns "OK" response
+    Given operation "ValidateDashboardWidgets" enabled
+    And new "ValidateDashboardWidgets" request
+    And body with value {"layout_type": "ordered", "reflow_type": "auto", "widgets": [{"definition": {"content": "Valid note", "type": "note"}}]}
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "results" has length 1
+    And the response "results[0].is_valid" is equal to true
+    And the response "results[0].widget_type" is equal to "note"
+    And the response "results[0]" has field "error_message"
+    And the response "results[0]" has field "error_path"
+
+  @generated @skip @team:DataDog/dashboards-backend
+  Scenario: Validate dashboard widgets returns "Unprocessable Entity" response
+    Given operation "ValidateDashboardWidgets" enabled
+    And new "ValidateDashboardWidgets" request
+    And body with value {"layout_type": "ordered", "reflow_type": "auto", "widgets": [{"definition": {"content": "Valid note", "type": "note"}}]}
+    When the request is sent
+    Then the response status is 422 Unprocessable Entity

features/v2/undo.json

@@ -2157,6 +2157,12 @@
       "type": "safe"
     }
   },
+  "ValidateDashboardWidgets": {
+    "tag": "Dashboards",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "ListSharedDashboardsByDashboardId": {
     "tag": "Dashboard Sharing",
     "undo": {

lib/datadog_api_client/configuration.rb

@@ -408,13 +408,14 @@ def initialize
             "v2.list_csm_agentless_hosts": false,
             "v2.list_csm_unified_host_facets": false,
             "v2.list_csm_unified_hosts": false,
+            "v2.get_dashboard_usage": false,
+            "v2.list_dashboards_usage": false,
+            "v2.validate_dashboard_widgets": false,
             "v2.list_shared_dashboards_by_dashboard_id": false,
             "v2.create_dashboard_secure_embed": false,
             "v2.delete_dashboard_secure_embed": false,
             "v2.get_dashboard_secure_embed": false,
             "v2.update_dashboard_secure_embed": false,
-            "v2.get_dashboard_usage": false,
-            "v2.list_dashboards_usage": false,
             "v2.get_data_observability_monitor_run_status": false,
             "v2.run_data_observability_monitor": false,
             "v2.create_dataset": false,

lib/datadog_api_client/inflector.rb

@@ -2837,6 +2837,11 @@ def overrides
           "v2.dashboard_usage_response" => "DashboardUsageResponse",
           "v2.dashboard_usage_type" => "DashboardUsageType",
           "v2.dashboard_usage_user" => "DashboardUsageUser",
+          "v2.dashboard_widget_validation_layout_type" => "DashboardWidgetValidationLayoutType",
+          "v2.dashboard_widget_validation_reflow_type" => "DashboardWidgetValidationReflowType",
+          "v2.dashboard_widget_validation_request" => "DashboardWidgetValidationRequest",
+          "v2.dashboard_widget_validation_response" => "DashboardWidgetValidationResponse",
+          "v2.dashboard_widget_validation_result" => "DashboardWidgetValidationResult",
           "v2.data_attributes_rules_items_if_tag_exists" => "DataAttributesRulesItemsIfTagExists",
           "v2.data_attributes_rules_items_mapping" => "DataAttributesRulesItemsMapping",
           "v2.database_monitoring_trigger_wrapper" => "DatabaseMonitoringTriggerWrapper",

lib/datadog_api_client/v2/api/dashboards_api.rb

@@ -191,5 +191,78 @@ def list_dashboards_usage_with_pagination(opts = {})
             @api_client.set_attribute_from_path(api_version, opts, "page_offset", Integer, @api_client.get_attribute_from_path(opts, "page_offset", 0) + page_size)
         end
     end
+
+    # Validate dashboard widgets.
+    #
+    # @see #validate_dashboard_widgets_with_http_info
+    def validate_dashboard_widgets(body, opts = {})
+      data, _status_code, _headers = validate_dashboard_widgets_with_http_info(body, opts)
+      data
+    end
+
+    # Validate dashboard widgets.
+    #
+    # Validate dashboard widgets without creating or updating a dashboard.
+    #
+    # @param body [DashboardWidgetValidationRequest] 
+    # @param opts [Hash] the optional parameters
+    # @return [Array<(DashboardWidgetValidationResponse, Integer, Hash)>] DashboardWidgetValidationResponse data, response status code and response headers
+    def validate_dashboard_widgets_with_http_info(body, opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.validate_dashboard_widgets".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.validate_dashboard_widgets")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.validate_dashboard_widgets"))
+      end
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: DashboardsAPI.validate_dashboard_widgets ...'
+      end
+      # verify the required parameter 'body' is set
+      if @api_client.config.client_side_validation && body.nil?
+        fail ArgumentError, "Missing the required parameter 'body' when calling DashboardsAPI.validate_dashboard_widgets"
+      end
+      # resource path
+      local_var_path = '/api/v2/dashboard/widgets/validate'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+      # HTTP header 'Content-Type'
+      header_params['Content-Type'] = @api_client.select_header_content_type(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(body)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'DashboardWidgetValidationResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
+
+      new_options = opts.merge(
+        :operation => :validate_dashboard_widgets,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Post, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: DashboardsAPI#validate_dashboard_widgets\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
   end
 end