Adding SLO Reporting API Documentation (#2426)

* add text/csv response print * Regenerate client from commit fc718bc2 of spec repo --------- Co-authored-by: Kevin Zou <kevin.zou@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>
DataDog · Apr 10, 2024 · 7cb4c6d · 7cb4c6d
1 parent 20ba525
commit 7cb4c6d
Show file tree

Hide file tree

Showing 39 changed files with 2,213 additions and 4 deletions.
diff --git a/.apigentools-info b/.apigentools-info
@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2024-04-08 20:24:06.756336",
-            "spec_repo_commit": "037e376a"
+            "regenerated": "2024-04-09 18:05:53.872718",
+            "spec_repo_commit": "fc718bc2"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2024-04-08 20:24:06.775222",
-            "spec_repo_commit": "037e376a"
+            "regenerated": "2024-04-09 18:05:53.890676",
+            "spec_repo_commit": "fc718bc2"
         }
     }
 }
diff --git a/.generator/schemas/v2/openapi.yaml b/.generator/schemas/v2/openapi.yaml
@@ -411,6 +411,13 @@ components:
       required: true
       schema:
         type: string
+    ReportID:
+      description: The ID of the report job.
+      in: path
+      name: report_id
+      required: true
+      schema:
+        type: string
     ResourceID:
       description: 'Identifier, formatted as `type:id`. Supported types: `connection`,
         `dashboard`, `notebook`, `security-rule`, `slo`.'
@@ -16574,6 +16581,74 @@ components:
       type: string
       x-enum-varnames:
       - SAML_ASSERTION_ATTRIBUTES
+    SLOReportInterval:
+      description: The frequency at which report data is to be generated.
+      enum:
+      - weekly
+      - monthly
+      example: weekly
+      type: string
+      x-enum-varnames:
+      - WEEKLY
+      - MONTHLY
+    SLOReportPostResponse:
+      description: The SLO report response.
+      properties:
+        data:
+          $ref: '#/components/schemas/SLOReportPostResponseData'
+      type: object
+    SLOReportPostResponseData:
+      description: The data portion of the SLO report response.
+      properties:
+        id:
+          description: The ID of the report job.
+          example: dc8d92aa-e0af-11ee-af21-1feeaccaa3a3
+          type: string
+        type:
+          description: The type of ID.
+          example: report_id
+          type: string
+      type: object
+    SLOReportStatus:
+      description: The status of the SLO report job.
+      enum:
+      - in_progress
+      - completed
+      - completed_with_errors
+      - failed
+      example: completed
+      type: string
+      x-enum-varnames:
+      - IN_PROGRESS
+      - COMPLETED
+      - COMPLETED_WITH_ERRORS
+      - FAILED
+    SLOReportStatusGetResponse:
+      description: The SLO report status response.
+      properties:
+        data:
+          $ref: '#/components/schemas/SLOReportStatusGetResponseData'
+      type: object
+    SLOReportStatusGetResponseAttributes:
+      description: The attributes portion of the SLO report status response.
+      properties:
+        status:
+          $ref: '#/components/schemas/SLOReportStatus'
+      type: object
+    SLOReportStatusGetResponseData:
+      description: The data portion of the SLO report status response.
+      properties:
+        attributes:
+          $ref: '#/components/schemas/SLOReportStatusGetResponseAttributes'
+        id:
+          description: The ID of the report job.
+          example: dc8d92aa-e0af-11ee-af21-1feeaccaa3a3
+          type: string
+        type:
+          description: The type of ID.
+          example: report_id
+          type: string
+      type: object
     ScalarColumn:
       description: A single column in a scalar query response.
       oneOf:
@@ -20216,6 +20291,53 @@ components:
       - channel_name
       - redirect_url
       type: object
+    SloReportCreateRequest:
+      description: The SLO report request body.
+      properties:
+        data:
+          $ref: '#/components/schemas/SloReportCreateRequestData'
+      required:
+      - data
+      type: object
+    SloReportCreateRequestAttributes:
+      description: The attributes portion of the SLO report request.
+      properties:
+        from_ts:
+          description: The `from` timestamp for the report in epoch seconds.
+          example: 1690901870
+          format: int64
+          type: integer
+        interval:
+          $ref: '#/components/schemas/SLOReportInterval'
+        query:
+          description: The query string used to filter SLO results. Some examples
+            of queries include `service:<service-name>` and `slo-name`.
+          example: slo_type:metric
+          type: string
+        timezone:
+          description: The timezone used to determine the start and end of each interval.
+            For example, weekly intervals start at 12am on Sunday in the specified
+            timezone.
+          example: America/New_York
+          type: string
+        to_ts:
+          description: The `to` timestamp for the report in epoch seconds.
+          example: 1706803070
+          format: int64
+          type: integer
+      required:
+      - query
+      - from_ts
+      - to_ts
+      type: object
+    SloReportCreateRequestData:
+      description: The data portion of the SLO report request.
+      properties:
+        attributes:
+          $ref: '#/components/schemas/SloReportCreateRequestAttributes'
+      required:
+      - attributes
+      type: object
     SortDirection:
       default: desc
       description: The direction to sort by.
@@ -33715,6 +33837,149 @@ paths:
       - Incident Services
       x-codegen-request-body-name: body
       x-unstable: '**Note**: This endpoint is deprecated.'
+  /api/v2/slo/report:
+    post:
+      description: 'Create a job to generate an SLO report. The report job is processed
+        asynchronously and eventually results in a CSV report being available for
+        download.
+
+
+        Check the status of the job and download the CSV report using the returned
+        `report_id`.'
+      operationId: CreateSLOReportJob
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SloReportCreateRequest'
+        description: Create SLO report job request body.
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SLOReportPostResponse'
+          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
+        '429':
+          $ref: '#/components/responses/TooManyRequestsResponse'
+      security:
+      - apiKeyAuth: []
+        appKeyAuth: []
+      - AuthZ:
+        - slos_read
+      summary: Create a new SLO report
+      tags:
+      - Service Level Objectives
+      x-codegen-request-body-name: body
+      x-unstable: '**Note**: This feature is in private beta. To request access, use
+        the request access form in the [Service Level Objectives](https://docs.datadoghq.com/service_management/service_level_objectives/#slo-csv-export)
+        docs.'
+  /api/v2/slo/report/{report_id}/download:
+    get:
+      description: 'Download an SLO report. This can only be performed after the report
+        job has completed.
+
+
+        Reports are not guaranteed to exist indefinitely. Datadog recommends that
+        you download the report as soon as it is available.'
+      operationId: GetSLOReport
+      parameters:
+      - $ref: '#/components/parameters/ReportID'
+      responses:
+        '200':
+          content:
+            text/csv:
+              schema:
+                type: string
+          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
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Not Found
+        '429':
+          $ref: '#/components/responses/TooManyRequestsResponse'
+      security:
+      - apiKeyAuth: []
+        appKeyAuth: []
+      - AuthZ:
+        - slos_read
+      summary: Get SLO report
+      tags:
+      - Service Level Objectives
+      x-unstable: '**Note**: This feature is in private beta. To request access, use
+        the request access form in the [Service Level Objectives](https://docs.datadoghq.com/service_management/service_level_objectives/#slo-csv-export)
+        docs.'
+  /api/v2/slo/report/{report_id}/status:
+    get:
+      description: Get the status of the SLO report job.
+      operationId: GetSLOReportJobStatus
+      parameters:
+      - $ref: '#/components/parameters/ReportID'
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SLOReportStatusGetResponse'
+          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
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Not Found
+        '429':
+          $ref: '#/components/responses/TooManyRequestsResponse'
+      security:
+      - apiKeyAuth: []
+        appKeyAuth: []
+      - AuthZ:
+        - slos_read
+      summary: Get SLO report status
+      tags:
+      - Service Level Objectives
+      x-unstable: '**Note**: This feature is in private beta. To request access, use
+        the request access form in the [Service Level Objectives](https://docs.datadoghq.com/service_management/service_level_objectives/#slo-csv-export)
+        docs.'
   /api/v2/spans/analytics/aggregate:
     post:
       description: 'The API endpoint to aggregate spans into buckets and compute metrics
@@ -36129,6 +36394,18 @@ tags:
   externalDocs:
     url: https://docs.datadoghq.com/tracing/service_catalog/
   name: Service Definition
+- description: '[Service Level Objectives](https://docs.datadoghq.com/monitors/service_level_objectives/#configuration)
+
+    (SLOs) are a key part of the site reliability engineering toolkit.
+
+    SLOs provide a framework for defining clear targets around application performance,
+
+    which ultimately help teams provide a consistent customer experience,
+
+    balance feature development with platform stability,
+
+    and improve communication with internal and external users.'
+  name: Service Level Objectives
 - description: 'API to create, update scorecard rules and outcomes. See [Service Scorecards](https://docs.datadoghq.com/service_catalog/scorecards)
     for more information.
 

diff --git a/.generator/src/generator/templates/example.j2 b/.generator/src/generator/templates/example.j2
@@ -83,6 +83,9 @@ func main() {
 
 	responseContent, _ := json.MarshalIndent(resp, "", "  ")
 	fmt.Fprintf(os.Stdout, "Response from `{{ context.api_instance.name }}Api.{{ context.api_request.operation_id }}`:\n%s\n", responseContent)
+	{%- elif contentType.startswith("text/csv") %}
+
+	fmt.Fprintf(os.Stdout, "Response from `{{ context.api_instance.name }}Api.{{ context.api_request.operation_id }}`:\n%s\n", resp)
 	{%- elif schema.get("schema", {}).get("format") == "binary" %}
 
 	responseContent, _ := ioutil.ReadAll(resp)

diff --git a/api/datadog/configuration.go b/api/datadog/configuration.go
@@ -364,6 +364,9 @@ func NewConfiguration() *Configuration {
 			"v2.GetIncidentService":           false,
 			"v2.ListIncidentServices":         false,
 			"v2.UpdateIncidentService":        false,
+			"v2.CreateSLOReportJob":           false,
+			"v2.GetSLOReport":                 false,
+			"v2.GetSLOReportJobStatus":        false,
 			"v2.CreateIncidentTeam":           false,
 			"v2.DeleteIncidentTeam":           false,
 			"v2.GetIncidentTeam":              false,