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: []