Add API documentation for image account transfers

specification/DigitalOcean-public.v2.yaml

@@ -1405,6 +1405,22 @@ paths:
     delete:
       $ref: "resources/images/images_delete.yml"
 
+  /v2/images/{image_id}/account_transfer:
+    post:
+      $ref: "resources/images/images_post_account_transfer_create.yml"
+
+  /v2/images/{image_id}/account_transfer/accept:
+    post:
+      $ref: "resources/images/images_post_account_transfer_accept.yml"
+
+  /v2/images/{image_id}/account_transfer/cancel:
+    post:
+      $ref: "resources/images/images_post_account_transfer_cancel.yml"
+
+  /v2/images/{image_id}/account_transfer/decline:
+    post:
+      $ref: "resources/images/images_post_account_transfer_decline.yml"
+
   /v2/images/{image_id}/actions:
     get:
       $ref: "resources/images/imageActions_list.yml"

specification/resources/images/examples/curl/images_post_account_transfer_accept.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"transfer_id": 3164444, "recipient_uuid": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"}' \
+    "https://api.digitalocean.com/v2/images/9375231/account_transfer/accept"

specification/resources/images/examples/curl/images_post_account_transfer_cancel.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"transfer_id": 3164444}' \
+    "https://api.digitalocean.com/v2/images/9375231/account_transfer/cancel"

specification/resources/images/examples/curl/images_post_account_transfer_create.yml

@@ -0,0 +1,15 @@
+lang: cURL
+source: |-
+  # transfer to email
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"recipient_email": "alice@example.com"}' \
+    "https://api.digitalocean.com/v2/images/7555620/account_transfer"
+
+  # transfer to team
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"recipient_uuid": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"}' \
+    "https://api.digitalocean.com/v2/images/9375231/account_transfer"

specification/resources/images/examples/curl/images_post_account_transfer_decline.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"transfer_id": 3164444}' \
+    "https://api.digitalocean.com/v2/images/9375231/account_transfer/decline"

specification/resources/images/images_post_account_transfer_accept.yml

@@ -0,0 +1,50 @@
+operationId: images_post_account_transfer_accept
+
+summary: Accept an Image Account Transfer
+
+description: |
+  To accept an account transfer for an image, send a POST request to
+  `/v2/images/$IMAGE_ID/account_transfer/accept`.
+
+tags:
+  - Images
+
+parameters:
+  - $ref: 'parameters.yml#/image_id'
+
+requestBody:
+  required: true
+
+  content:
+    application/json:
+      schema:
+        $ref: 'models/images_post_account_transfer_accept.yml'
+
+responses:
+  '201':
+    $ref: '../../shared/responses/no_content.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.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/images_post_account_transfer_accept.yml'
+
+security:
+  - bearer_auth:
+    - 'image:create'

specification/resources/images/images_post_account_transfer_cancel.yml

@@ -0,0 +1,54 @@
+operationId: images_post_account_transfer_cancel
+
+summary: Cancel an Image Account Transfer
+
+description: |
+  To cancel an account transfer for an image, send a POST request to
+  `/v2/images/$IMAGE_ID/account_transfer/cancel`.
+
+  Only the sender of an image account transfer can cancel the transfer.
+  If the transfer is canceled, the image will remain in the sender's account
+  and will not be transferred to the recipient.
+
+tags:
+  - Images
+
+parameters:
+  - $ref: 'parameters.yml#/image_id'
+
+requestBody:
+  required: true
+
+  content:
+    application/json:
+      schema:
+        $ref: 'models/images_post_account_transfer_cancel.yml'
+
+responses:
+  '204':
+    $ref: '../../shared/responses/no_content.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.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/images_post_account_transfer_cancel.yml'
+
+security:
+  - bearer_auth:
+    - 'image:update'

specification/resources/images/images_post_account_transfer_create.yml

@@ -0,0 +1,66 @@
+operationId: images_post_account_transfer_create
+
+summary: Initiate an Image Account Transfer
+
+description: |
+  To initiate an account transfer for an image, send a POST request to
+  `/v2/images/$IMAGE_ID/account_transfer`.
+
+  Only snapshot images may be transferred by this endpoint to another account.
+
+  An image account transfer always has exactly one recipient, specified in the request body.
+  The recipient can be one of the following:
+
+  * A DigitalOcean account, denoted by `recipient_email` in the request body.
+  The recipient will receive an email with instructions to accept the transfer.
+  Once the recipient accepts the transfer, the image will be moved to their
+  account.
+
+  * A DigitalOcean team, denoted by `recipient_uuid` in the request body. If the
+  user has sufficient permissions in the recipient team, the transfer will be
+  automatically accepted and the image will be moved to the recipient team's
+  account. Otherwise, the transfer will be pending until a user with sufficient
+  permissions in the recipient team accepts the transfer.
+tags:
+  - Images
+
+parameters:
+  - $ref: 'parameters.yml#/image_id'
+
+requestBody:
+  required: true
+
+  content:
+    application/json:
+      schema:
+        $ref: 'models/images_post_account_transfer_create.yml'
+
+responses:
+  '201':
+    $ref: 'responses/images_post_account_transfer_created.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.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/images_post_account_transfer_create.yml'
+
+security:
+  - bearer_auth:
+    - 'image:update'
+    - 'image:delete'

specification/resources/images/images_post_account_transfer_decline.yml

@@ -0,0 +1,54 @@
+operationId: images_post_account_transfer_decline
+
+summary: Decline an Image Account Transfer
+
+description: |
+  To decline an account transfer for an image, send a POST request to
+  `/v2/images/$IMAGE_ID/account_transfer/decline`.
+
+  Only the recipient of an image account transfer can decline the transfer.
+  If the transfer is declined, the image will remain in the sender's account
+  and will not be transferred to the recipient.
+
+tags:
+  - Images
+
+parameters:
+  - $ref: 'parameters.yml#/image_id'
+
+requestBody:
+  required: true
+
+  content:
+    application/json:
+      schema:
+        $ref: 'models/images_post_account_transfer_decline.yml'
+
+responses:
+  '204':
+    $ref: '../../shared/responses/no_content.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.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/images_post_account_transfer_decline.yml'
+
+security:
+  - bearer_auth:
+    - 'image:create'

specification/resources/images/models/images_post_account_transfer_accept.yml

@@ -0,0 +1,21 @@
+allOf:
+  - title: Transfer ID
+    type: object
+    properties:
+      transfer_id:
+        type: integer
+        description: >-
+          A unique number that used to identify and reference an image account transfer.
+        example: 3164444
+    required:
+      - transfer_id
+
+  - title: Recipient Team UUID
+    type: object
+    properties:
+      recipient_uuid:
+        type: string
+        description: The UUID of the team that the image will be transferred to.
+        example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
+    required:
+      - recipient_uuid