Document API changes supporting new Droplet backup policies (#911)

* droplet: add backup_policy to create requests.

* droplet actions: add backup_policy to enable_backups action

* droplet actions: add change_backup_policy action

* droplet: add /v2/droplets/backups/supported_policies endpoint.

* droplet: add /v2/droplets/{droplet_id}/backups/policy endpoint.

* Update descriptions for clarity.

* droplet: add /v2/droplets/backups/policies endpoint.

* Additional examples.

* Rename droplet_backup_policy_record

specification/DigitalOcean-public.v2.yaml

@@ -911,6 +911,18 @@ paths:
     get:
       $ref: 'resources/droplets/droplets_list_backups.yml'
 
+  /v2/droplets/{droplet_id}/backups/policy:
+    get:
+      $ref: 'resources/droplets/droplets_get_backup_policy.yml'
+
+  /v2/droplets/backups/policies:
+    get:
+      $ref: 'resources/droplets/droplets_list_backup_policies.yml'
+
+  /v2/droplets/backups/supported_policies:
+    get:
+      $ref: 'resources/droplets/droplets_list_supported_backup_policies.yml'
+
   /v2/droplets/{droplet_id}/snapshots:
     get:
       $ref: 'resources/droplets/droplets_list_snapshots.yml'

specification/resources/droplets/dropletActions_post.yml

@@ -11,6 +11,7 @@ description: |
     | ---------------------------------------- | ----------- |
     | <nobr>`enable_backups`</nobr>            | Enables backups for a Droplet |
     | <nobr>`disable_backups`</nobr>           | Disables backups for a Droplet |
+    | <nobr>`change_backup_policy`</nobr>      | Update the backup policy for a Droplet |
     | <nobr>`reboot`</nobr>                    | Reboots a Droplet. A `reboot` action is an attempt to reboot the Droplet in a graceful way, similar to using the `reboot` command from the console. |
     | <nobr>`power_cycle`</nobr>               | Power cycles a Droplet. A `powercycle` action is similar to pushing the reset button on a physical machine, it's similar to booting from scratch. |
     | <nobr>`shutdown`</nobr>                  | Shutsdown a Droplet. A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the `shutdown` command from the console. Since a `shutdown` command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a `power_off` action to ensure the Droplet is off. |
@@ -42,6 +43,8 @@ requestBody:
       schema:
         anyOf:
           - $ref: 'models/droplet_actions.yml#/droplet_action'
+          - $ref: 'models/droplet_actions.yml#/droplet_action_enable_backups'
+          - $ref: 'models/droplet_actions.yml#/droplet_action_change_backup_policy'
           - $ref: 'models/droplet_actions.yml#/droplet_action_restore'
           - $ref: 'models/droplet_actions.yml#/droplet_action_resize'
           - $ref: 'models/droplet_actions.yml#/droplet_action_rebuild'
@@ -51,8 +54,9 @@ requestBody:
         discriminator:
           propertyName: type
           mapping:
-            enable_backups: 'models/droplet_actions.yml#/droplet_action'
+            enable_backups: 'models/droplet_actions.yml#/droplet_action_enable_backups'
             disable_backups: 'models/droplet_actions.yml#/droplet_action'
+            change_backup_policy: 'models/droplet_actions.yml#/droplet_action_change_backup_policy'
             reboot: 'models/droplet_actions.yml#/droplet_action'
             power_cycle: 'models/droplet_actions.yml#/droplet_action'
             shutdown: 'models/droplet_actions.yml#/droplet_action'

specification/resources/droplets/droplets_get_backup_policy.yml

@@ -0,0 +1,39 @@
+operationId: droplets_get_backup_policy
+
+summary: Retrieve the Backup Policy for an Existing Droplet
+
+description: |
+  To show information about an individual Droplet's backup policy, send a GET
+  request to `/v2/droplets/$DROPLET_ID/backups/policy`.
+
+tags:
+  - Droplets
+
+parameters:
+  - $ref: 'parameters.yml#/droplet_id'
+
+responses:
+  '200':
+    $ref: 'responses/droplet_backup_policy.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/droplets_get_backup_policy.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/droplets/droplets_list_backup_policies.yml

@@ -0,0 +1,40 @@
+operationId: droplets_list_backup_policies
+
+summary: List Backup Policies for All Existing Droplets
+
+description: |
+  To list information about the backup policies for all Droplets in the account,
+  send a GET request to `/v2/droplets/backups/policies`.
+
+tags:
+  - Droplets
+
+parameters:
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+
+responses:
+  '200':
+    $ref: 'responses/all_droplet_backup_policies.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/droplets_list_backup_policies.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/droplets/droplets_list_supported_backup_policies.yml

@@ -0,0 +1,36 @@
+operationId: droplets_list_supported_backup_policies
+
+summary: List Supported Droplet Backup Policies
+
+description: |
+  To retrieve a list of all supported Droplet backup policies, send a GET
+  request to `/v2/droplets/backups/supported_policies`.
+
+tags:
+  - Droplets
+
+responses:
+  '200':
+    $ref: 'responses/droplets_supported_backup_policies.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/droplets_list_supported_backup_policies.yml'
+
+security:
+  - bearer_auth:
+    - 'droplet:read'

specification/resources/droplets/examples/curl/droplets_get_backup_policy.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/droplets/3164494/backups/policy"

specification/resources/droplets/examples/curl/droplets_list_backup_policies.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/droplets/backups/policies"

specification/resources/droplets/examples/curl/droplets_list_supported_backup_policies.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/droplets/backups/supported_policies"

specification/resources/droplets/models/droplet.yml

@@ -76,24 +76,11 @@ properties:
       instance creation.
 
   next_backup_window:
-    type: object
-    description: The details of the Droplet's backups feature, if backups are
-      configured for the Droplet. This object contains keys for the start and
-      end times of the window during which the backup will start.
-    nullable: true
-    properties:
-      start:
-        type: string
-        format: date-time
-        example: '2019-12-04T00:00:00Z'
-        description: A time value given in ISO8601 combined date and time format
-          specifying the start of the Droplet's backup window.
-      end:
-        type: string
-        format: date-time
-        example: '2019-12-04T23:00:00Z'
-        description: A time value given in ISO8601 combined date and time format
-          specifying the end of the Droplet's backup window.
+    allOf:
+    - $ref: 'droplet_next_backup_window.yml'
+    - description: The details of the Droplet's backups feature, if backups are
+        configured for the Droplet. This object contains keys for the start and
+        end times of the window during which the backup will start.
 
   snapshot_ids:
     type: array

specification/resources/droplets/models/droplet_actions.yml

@@ -25,6 +25,42 @@ droplet_action:
       example: reboot
       description: The type of action to initiate for the Droplet.
 
+droplet_action_enable_backups:
+  allOf:
+  - $ref: '#/droplet_action'
+  - type: object
+    properties:
+      backup_policy:
+        allOf:
+        - $ref: 'droplet_backup_policy.yml'
+        - description: An object specifying the backup policy for the Droplet. If
+            omitted, the default backup policy will be used.
+
+  example:
+    type: enable_backups
+    backup_policy:
+      plan: daily
+      hour: 20
+
+droplet_action_change_backup_policy:
+  allOf:
+  - $ref: '#/droplet_action'
+  - type: object
+    properties:
+      backup_policy:
+        allOf:
+        - $ref: 'droplet_backup_policy.yml'
+        - description: An object specifying the backup policy for the Droplet.
+  required:
+  - backup_policy
+
+  example:
+    type: enable_backups
+    backup_policy:
+      plan: weekly
+      day: SUN
+      hour: 20
+
 droplet_action_restore:
   allOf:
   - $ref: '#/droplet_action'

specification/resources/droplets/models/droplet_backup_policy.yml

@@ -0,0 +1,48 @@
+type: object
+
+properties:
+  plan:
+    type: string
+    enum:
+    - daily
+    - weekly
+    example: daily
+    description: The backup plan used for the Droplet. The plan can be either
+      `daily` or `weekly`.
+
+  weekday:
+    type: string
+    enum:
+    - SUN
+    - MON
+    - TUE
+    - WED
+    - THU
+    - FRI
+    - SAT
+    example: SUN
+    description: The day of the week on which the backup will occur.
+
+  hour:
+    type: integer
+    enum:
+    - 0
+    - 4
+    - 8
+    - 12
+    - 16
+    - 20
+    example: 0
+    description: The hour of the day that the backup window will start.
+
+  window_length_hours:
+    type: integer
+    readOnly: true
+    example: 4
+    description: The length of the backup window starting from `hour`.
+
+  retention_period_days:
+    type: integer
+    readOnly: true
+    example: 7
+    description: The number of days the backup will be retained.

specification/resources/droplets/models/droplet_backup_policy_record.yml

@@ -0,0 +1,24 @@
+type: object
+
+properties:
+  droplet_id:
+    type: integer
+    example: 7101383
+    description: The unique identifier for the Droplet.
+
+  backup_enabled:
+    type: boolean
+    example: true
+    description: A boolean value indicating whether backups are enabled for the
+      Droplet.
+
+  backup_policy:
+    allOf:
+      - $ref: 'droplet_backup_policy.yml'
+      - description: An object specifying the backup policy for the Droplet.
+
+  next_backup_window:
+    allOf:
+    - $ref: 'droplet_next_backup_window.yml'
+    - description: An object containing keys with the start and end times of the
+        window during which the backup will occur.

specification/resources/droplets/models/droplet_create.yml

@@ -45,6 +45,12 @@ properties:
     description: A boolean indicating whether automated backups should be enabled
       for the Droplet.
 
+  backup_policy:
+    allOf:
+      - $ref: 'droplet_backup_policy.yml'
+      - description: An object specifying the backup policy for the Droplet. If
+          omitted and `backups` is `true`, the default backup policy will be used.
+
   ipv6:
     type: boolean
     example: true

specification/resources/droplets/models/droplet_next_backup_window.yml

@@ -0,0 +1,15 @@
+type: object
+nullable: true
+properties:
+  start:
+    type: string
+    format: date-time
+    example: '2019-12-04T00:00:00Z'
+    description: A time value given in ISO8601 combined date and time format
+      specifying the start of the Droplet's backup window.
+  end:
+    type: string
+    format: date-time
+    example: '2019-12-04T23:00:00Z'
+    description: A time value given in ISO8601 combined date and time format
+      specifying the end of the Droplet's backup window.

specification/resources/droplets/models/supported_droplet_backup_policy.yml

@@ -0,0 +1,39 @@
+type: object
+
+properties:
+  name:
+    type: string
+    example: daily
+    description: The name of the Droplet backup plan.
+
+  possible_window_starts:
+    type: array
+    items:
+      type: integer
+    description: |
+      An array of integers representing the hours of the day that a backup can
+      start.
+    example:
+    - 0
+    - 4
+    - 8
+    - 12
+    - 16
+    - 20
+
+  window_length_hours:
+    type: integer
+    example: 4
+    description: The number of hours that a backup window is open.
+
+  retention_period_days:
+    type: integer
+    example: 7
+    description: The number of days that a backup will be kept.
+
+  possible_days:
+    type: array
+    items:
+      type: string
+    example: ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
+    description: The day of the week the backup will occur.