diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml
index 8fa492bd6..6315c24e5 100644
--- a/specification/DigitalOcean-public.v2.yaml
+++ b/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'
diff --git a/specification/resources/droplets/dropletActions_post.yml b/specification/resources/droplets/dropletActions_post.yml
index 1f085ebcc..c150ce23c 100644
--- a/specification/resources/droplets/dropletActions_post.yml
+++ b/specification/resources/droplets/dropletActions_post.yml
@@ -11,6 +11,7 @@ description: |
| ---------------------------------------- | ----------- |
| `enable_backups` | Enables backups for a Droplet |
| `disable_backups` | Disables backups for a Droplet |
+ | `change_backup_policy` | Update the backup policy for a Droplet |
| `reboot` | 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. |
| `power_cycle` | 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. |
| `shutdown` | 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'
diff --git a/specification/resources/droplets/droplets_get_backup_policy.yml b/specification/resources/droplets/droplets_get_backup_policy.yml
new file mode 100644
index 000000000..2cff6149a
--- /dev/null
+++ b/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'
diff --git a/specification/resources/droplets/droplets_list_backup_policies.yml b/specification/resources/droplets/droplets_list_backup_policies.yml
new file mode 100644
index 000000000..c0f013635
--- /dev/null
+++ b/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'
diff --git a/specification/resources/droplets/droplets_list_supported_backup_policies.yml b/specification/resources/droplets/droplets_list_supported_backup_policies.yml
new file mode 100644
index 000000000..f6974eaf4
--- /dev/null
+++ b/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'
diff --git a/specification/resources/droplets/examples/curl/droplets_get_backup_policy.yml b/specification/resources/droplets/examples/curl/droplets_get_backup_policy.yml
new file mode 100644
index 000000000..bcc387808
--- /dev/null
+++ b/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"
diff --git a/specification/resources/droplets/examples/curl/droplets_list_backup_policies.yml b/specification/resources/droplets/examples/curl/droplets_list_backup_policies.yml
new file mode 100644
index 000000000..c5936fc79
--- /dev/null
+++ b/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"
diff --git a/specification/resources/droplets/examples/curl/droplets_list_supported_backup_policies.yml b/specification/resources/droplets/examples/curl/droplets_list_supported_backup_policies.yml
new file mode 100644
index 000000000..2978a1936
--- /dev/null
+++ b/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"
diff --git a/specification/resources/droplets/models/droplet.yml b/specification/resources/droplets/models/droplet.yml
index 77e04c36f..778e0acf2 100644
--- a/specification/resources/droplets/models/droplet.yml
+++ b/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
diff --git a/specification/resources/droplets/models/droplet_actions.yml b/specification/resources/droplets/models/droplet_actions.yml
index 8acc39ad2..19e895d19 100644
--- a/specification/resources/droplets/models/droplet_actions.yml
+++ b/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'
diff --git a/specification/resources/droplets/models/droplet_backup_policy.yml b/specification/resources/droplets/models/droplet_backup_policy.yml
new file mode 100644
index 000000000..9078d776b
--- /dev/null
+++ b/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.
diff --git a/specification/resources/droplets/models/droplet_backup_policy_record.yml b/specification/resources/droplets/models/droplet_backup_policy_record.yml
new file mode 100644
index 000000000..a8188130f
--- /dev/null
+++ b/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.
diff --git a/specification/resources/droplets/models/droplet_create.yml b/specification/resources/droplets/models/droplet_create.yml
index 0a6d7ff8e..637217044 100644
--- a/specification/resources/droplets/models/droplet_create.yml
+++ b/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
diff --git a/specification/resources/droplets/models/droplet_next_backup_window.yml b/specification/resources/droplets/models/droplet_next_backup_window.yml
new file mode 100644
index 000000000..dda61ca28
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/specification/resources/droplets/models/supported_droplet_backup_policy.yml b/specification/resources/droplets/models/supported_droplet_backup_policy.yml
new file mode 100644
index 000000000..cce53985e
--- /dev/null
+++ b/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.
diff --git a/specification/resources/droplets/responses/all_droplet_backup_policies.yml b/specification/resources/droplets/responses/all_droplet_backup_policies.yml
new file mode 100644
index 000000000..aad1f25d1
--- /dev/null
+++ b/specification/resources/droplets/responses/all_droplet_backup_policies.yml
@@ -0,0 +1,58 @@
+description: A JSON object with a `policies` key set to a map. The keys are
+ Droplet IDs and the values are objects containing the backup policy
+ information for each Droplet.
+
+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'
+
+content:
+ application/json:
+ schema:
+ allOf:
+ - type: object
+ properties:
+ policies:
+ description: |
+ A map where the keys are the Droplet IDs and the values are
+ objects containing the backup policy information for each Droplet.
+ additionalProperties:
+ $ref: '../models/droplet_backup_policy_record.yml'
+ - $ref: '../../../shared/pages.yml#/pagination'
+ - $ref: '../../../shared/meta.yml'
+
+ example:
+ policies:
+ "436444618":
+ droplet_id: 436444618
+ backup_enabled: false
+ "444909314":
+ droplet_id: 444909314
+ backup_enabled: true
+ backup_policy:
+ plan: daily
+ hour: 20
+ window_length_hours: 4
+ retention_period_days: 7
+ next_backup_window:
+ start: "2024-09-13T20:00:00Z"
+ end: "2024-09-14T00:00:00Z"
+ "444909706":
+ droplet_id: 444909706
+ backup_enabled: true
+ backup_policy:
+ plan: weekly
+ weekday: SUN
+ hour: 20
+ window_length_hours: 4
+ retention_period_days: 28
+ next_backup_window:
+ start: "2024-09-15T20:00:00Z"
+ end: "2024-09-16T00:00:00Z"
+ links: {}
+ meta:
+ total: 3
diff --git a/specification/resources/droplets/responses/droplet_backup_policy.yml b/specification/resources/droplets/responses/droplet_backup_policy.yml
new file mode 100644
index 000000000..0fc161ec1
--- /dev/null
+++ b/specification/resources/droplets/responses/droplet_backup_policy.yml
@@ -0,0 +1,32 @@
+description: |
+ The response will be a JSON object with a key called `policy`. This will be
+ set to a JSON object that contains the standard Droplet backup policy attributes.
+
+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'
+
+content:
+ application/json:
+ schema:
+ properties:
+ policy:
+ $ref: '../models/droplet_backup_policy_record.yml'
+
+ example:
+ policy:
+ droplet_id: 444909706
+ backup_enabled: true
+ backup_policy:
+ plan: "weekly"
+ weekday: "SUN"
+ hour: 20
+ window_length_hours: 4
+ retention_period_days: 28
+ next_backup_window:
+ start: "2024-09-15T20:00:00Z"
+ end: "2024-09-16T00:00:00Z"
diff --git a/specification/resources/droplets/responses/droplets_supported_backup_policies.yml b/specification/resources/droplets/responses/droplets_supported_backup_policies.yml
new file mode 100644
index 000000000..6ae6be4b7
--- /dev/null
+++ b/specification/resources/droplets/responses/droplets_supported_backup_policies.yml
@@ -0,0 +1,53 @@
+description: A JSON object with an `supported_policies` key set to an array
+ of objects describing each supported backup policy.
+
+
+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'
+
+content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ supported_policies:
+ type: array
+ items:
+ $ref: '../models/supported_droplet_backup_policy.yml'
+
+ example:
+ supported_policies:
+ - name: "weekly"
+ possible_window_starts:
+ - 0
+ - 4
+ - 8
+ - 12
+ - 16
+ - 20
+ window_length_hours: 4
+ retention_period_days: 28
+ possible_days":
+ - "SUN"
+ - "MON"
+ - "TUE"
+ - "WED"
+ - "THU"
+ - "FRI"
+ - "SAT"
+ - name: "daily"
+ possible_window_starts:
+ - 0
+ - 4
+ - 8
+ - 12
+ - 16
+ - 20
+ window_length_hours: 4
+ retention_period_days: 7
+ possible_days: []