Add ListEvents, CancelEvent, and GetEventLogs OpenAPI specs for App Platform

specification/DigitalOcean-public.v2.yaml

@@ -739,6 +739,22 @@ paths:
     get:
       $ref: "resources/apps/apps_get_job_invocation_logs.yml"
 
+  /v2/apps/{app_id}/events:
+    get:
+      $ref: "resources/apps/apps_list_events.yml"
+
+  /v2/apps/{app_id}/events/{event_id}:
+    get:
+      $ref: "resources/apps/apps_get_event.yml"
+
+  /v2/apps/{app_id}/events/{event_id}/cancel:
+    post:
+      $ref: "resources/apps/apps_cancel_event.yml"
+
+  /v2/apps/{app_id}/events/{event_id}/logs:
+    get:
+      $ref: "resources/apps/apps_get_event_logs.yml"
+
   /v2/apps/tiers/instance_sizes:
     get:
       $ref: "resources/apps/apps_list_instanceSizes.yml"

specification/resources/apps/apps_cancel_event.yml

@@ -0,0 +1,39 @@
+operationId: apps_cancel_event
+
+summary: Cancel an Event
+
+description: Cancel an in-progress autoscaling event.
+
+tags:
+- Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+  - $ref: parameters.yml#/event_id
+
+responses:
+  "200":
+    $ref: responses/cancel_event.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  "429":
+    $ref: "../../shared/responses/too_many_requests.yml"
+
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+
+x-codeSamples:
+  - $ref: 'examples/curl/apps_cancel_event.yml'
+  - $ref: 'examples/python/apps_cancel_event.yml'
+
+security:
+  - bearer_auth:
+    - 'app:update'

specification/resources/apps/apps_get_event.yml

@@ -0,0 +1,39 @@
+operationId: apps_get_event
+
+summary: Get an Event
+
+description: Get a single event for an app.
+
+tags:
+- Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+  - $ref: parameters.yml#/event_id
+
+responses:
+  "200":
+    $ref: responses/get_event.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  "429":
+    $ref: "../../shared/responses/too_many_requests.yml"
+
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+
+x-codeSamples:
+  - $ref: 'examples/curl/apps_get_event.yml'
+  - $ref: 'examples/python/apps_get_event.yml'
+
+security:
+  - bearer_auth:
+    - 'app:read'

specification/resources/apps/apps_get_event_logs.yml

@@ -0,0 +1,42 @@
+operationId: apps_get_event_logs
+
+summary: Retrieve Event Logs
+
+description: Retrieve the logs of an autoscaling event for an app.
+
+tags:
+- Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+  - $ref: parameters.yml#/event_id
+  - $ref: parameters.yml#/live_updates
+  - $ref: parameters.yml#/log_type
+  - $ref: parameters.yml#/time_wait
+
+responses:
+  "200":
+    $ref: responses/list_logs.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  "429":
+    $ref: "../../shared/responses/too_many_requests.yml"
+
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+
+x-codeSamples:
+  - $ref: 'examples/curl/apps_get_event_logs.yml'
+  - $ref: 'examples/python/apps_get_event_logs.yml'
+
+security:
+  - bearer_auth:
+    - 'app:read'

specification/resources/apps/apps_list_events.yml

@@ -0,0 +1,53 @@
+operationId: apps_list_events
+
+summary: List App Events
+
+description: List all events for an app, including deployments and autoscaling events.
+
+tags:
+- Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+  - $ref: ../../shared/parameters.yml#/page
+  - $ref: ../../shared/parameters.yml#/per_page
+  - description: Filter events by event type.
+    in: query
+    name: event_types
+    required: false
+    schema:
+      type: array
+      items:
+        type: string
+        enum:
+          - UNKNOWN
+          - DEPLOYMENT
+          - AUTOSCALING
+    example: [DEPLOYMENT]
+
+responses:
+  "200":
+    $ref: responses/list_events.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.yml
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  "429":
+    $ref: "../../shared/responses/too_many_requests.yml"
+
+  "500":
+    $ref: ../../shared/responses/server_error.yml
+
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+
+x-codeSamples:
+  - $ref: 'examples/curl/apps_list_events.yml'
+  - $ref: 'examples/python/apps_list_events.yml'
+
+security:
+  - bearer_auth:
+    - 'app:read'

specification/resources/apps/examples/curl/apps_cancel_event.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}/cancel"

specification/resources/apps/examples/curl/apps_get_event.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}"

specification/resources/apps/examples/curl/apps_get_event_logs.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}/logs?type=AUTOSCALE_EVENT"

specification/resources/apps/examples/curl/apps_list_events.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/{app_id}/events"

specification/resources/apps/examples/python/apps_cancel_event.yml

@@ -0,0 +1,8 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  get_resp = client.apps.cancel_event(app_id="4f6c71e2", event_id="3aa4d20e")

specification/resources/apps/examples/python/apps_get_event.yml

@@ -0,0 +1,8 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  get_resp = client.apps.get_event(app_id="4f6c71e2", event_id="3aa4d20e")

specification/resources/apps/examples/python/apps_get_event_logs.yml

@@ -0,0 +1,8 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  get_resp = client.apps.get_event_logs(app_id="4f6c71e2", event_id="3aa4d20e")

specification/resources/apps/examples/python/apps_list_events.yml

@@ -0,0 +1,8 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  get_resp = client.apps.list_events(app_id="4f6c71e2")

specification/resources/apps/models/app_event.yml

@@ -0,0 +1,66 @@
+type: object
+properties:
+  id:
+    type: string
+    title: The ID of the event (UUID)
+    example: "ba32b134-569c-4c0c-ba02-8ffdb0492ece"
+  type:
+    type: string
+    description: The type of event
+    enum:
+      - UNKNOWN
+      - DEPLOYMENT
+      - AUTOSCALING
+    example: DEPLOYMENT
+  created_at:
+    type: string
+    format: date-time
+    title: When the event was created
+    example: "2023-10-01T12:00:00Z"
+  deployment_id:
+    type: string
+    title: The deployment ID associated with this event
+    description: >-
+      For deployment events, this is the same as the deployment's ID.
+      For autoscaling events, this is the deployment that was autoscaled.
+    example: "c020763f-ddb7-4112-a0df-7f01c69fc00b"
+  deployment:
+    $ref: apps_deployment.yml
+  autoscaling:
+    type: object
+    description: Autoscaling event details. Only present for autoscaling events.
+    properties:
+      phase:
+        type: string
+        description: The current phase of the autoscaling event
+        enum:
+          - UNKNOWN
+          - PENDING
+          - IN_PROGRESS
+          - SUCCEEDED
+          - FAILED
+          - CANCELED
+        example: SUCCEEDED
+      components:
+        type: object
+        description: Map of component names to their scale changes
+        additionalProperties:
+          type: object
+          properties:
+            from:
+              type: integer
+              format: int64
+              description: The number of replicas before scaling
+              example: 1
+            to:
+              type: integer
+              format: int64
+              description: The number of replicas after scaling
+              example: 3
+            triggering_metric:
+              type: string
+              description: >-
+                The metric that triggered the scale change. Known values are
+                "cpu", "requests_per_second", "request_duration". For
+                inactivity sleep, "scale_from_zero" and "scale_to_zero" are used.
+              example: cpu

specification/resources/apps/models/app_events.yml

@@ -0,0 +1,9 @@
+allOf:
+  - type: object
+    properties:
+      events:
+        title: A list of events
+        type: array
+        items:
+          $ref: app_event.yml
+  - $ref: ../../../shared/pages.yml#/pagination

specification/resources/apps/parameters.yml

@@ -40,6 +40,15 @@ deployment_id:
     type: string
   example: 3aa4d20e-5527-4c00-b496-601fbd22520a
 
+event_id:
+  description: The event ID
+  in: path
+  name: event_id
+  required: true
+  schema:
+    type: string
+  example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
+
 app_name:
   description: The name of the app to retrieve.
   in: query
@@ -100,6 +109,7 @@ log_type:
     - DEPLOY: Deploy-time logs
     - RUN: Live run-time logs
     - RUN_RESTARTED: Logs of crashed/restarted instances during runtime
+    - AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id)
   in: query
   name: type
   required: true
@@ -111,6 +121,7 @@ log_type:
       - DEPLOY
       - RUN
       - RUN_RESTARTED
+      - AUTOSCALE_EVENT
     type: string
   example: BUILD
 

specification/resources/apps/responses/cancel_event.yml

@@ -0,0 +1,17 @@
+description: A JSON with key `event`
+
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        event:
+          $ref: ../models/app_event.yml
+
+headers:
+  ratelimit-limit:
+    $ref: ../../../shared/headers.yml#/ratelimit-limit
+  ratelimit-remaining:
+    $ref: ../../../shared/headers.yml#/ratelimit-remaining
+  ratelimit-reset:
+    $ref: ../../../shared/headers.yml#/ratelimit-reset