Add documentation for initiating image account transfers

Author: phan-do

specification/DigitalOcean-public.v2.yaml

@@ -1405,6 +1405,10 @@ paths:
     delete:
       $ref: "resources/images/images_delete.yml"
 
+  /v2/images/{image_id}/account_transfer:
+    post:
+      $ref: "resources/images/images_account_transfer_create.yml"
+
   /v2/images/{image_id}/actions:
     get:
       $ref: "resources/images/imageActions_list.yml"

specification/resources/images/examples/curl/images_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/images_account_transfer_create.yml

@@ -0,0 +1,63 @@
+operationId: images_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_account_transfer_create.yml'
+
+responses:
+  '201':
+    $ref: 'responses/images_account_transfer_created.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/images_account_transfer_create.yml'
+
+security:
+  - bearer_auth:
+    - 'image:update'
+    - 'image:delete'

specification/resources/images/models/images_account_transfer_create.yml

@@ -0,0 +1,20 @@
+oneOf:
+  - title: Transfer To Email
+    type: object
+    properties:
+      recipient_email:
+        type: string
+        example: alice@example.com
+        description: The email address of the user account that the image will be transferred to.
+    required:
+      - recipient_email
+
+  - title: Transfer To Team
+    type: object
+    properties:
+      recipient_uuid:
+        type: string
+        example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
+        description: The UUID of the team that the image will be transferred to.
+    required:
+      - recipient_uuid

specification/resources/images/models/transfer_id.yml

@@ -0,0 +1,4 @@
+type: integer
+description: |
+  A unique number that can be used to identify and reference an image
+  account transfer.

specification/resources/images/responses/images_account_transfer_created.yml

@@ -0,0 +1,23 @@
+description: >-
+  The response will be a JSON object with a key called `transfer_id`. 
+  The value of this will be a number that identifies the initiated transfer. If
+  the value is `0`, then the transfer has been accepted. Otherwise, the
+  transfer is pending and waiting for the recipient to accept it.
+
+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:
+        transfer_id:
+          $ref: '../models/transfer_id.yml'
+    
+    example:
+      transfer_id: 3164444