Merge branch 'main' into drop-11250

Author: a-talsma

specification/DigitalOcean-public.v2.yaml

@@ -365,6 +365,12 @@ tags:
       policies based on these metrics. The Monitoring API can help you gain insight into how your apps are performing
       and consuming resources.
 
+  - name: Partner Network Connect
+    description: |-
+      Partner Network Connect lets you establish high-bandwidth, low-latency
+      network connections directly between DigitalOcean VPC networks and other
+      public cloud providers or on-premises datacenters.
+
   - name: Project Resources
     description: |-
       Project Resources are resources that can be grouped into your projects.
@@ -404,12 +410,6 @@ tags:
       `already_assigned` | The resource was already assigned.
       `service_down`     | There was a problem retrieving or assigning a resource. Please try again.
 
-  - name: Partner Network Connect
-    description: |-
-      Partner Network Connect lets you establish high-bandwidth, low-latency
-      network connections directly between DigitalOcean VPC networks and other
-      public cloud providers or on-premises datacenters.
-
   - name: Projects
     description: |-
       Projects allow you to organize your resources into groups that fit the way
@@ -478,6 +478,18 @@ tags:
       An action object is returned. These objects hold the current status of the
       requested action.
 
+  - name: "[Public Preview] BYOIP Prefixes"
+    description: |-
+      Bring your own IP (BYOIP) lets you provision your own IPv4 network prefixes
+      to your account, then assign those IPs to your DigitalOcean resources. 
+      BYOIP supports the following features:
+      * IPv4 addresses
+      * Network sizes of anywhere from `/24` (256 addresses) to `/18` (16,384 addresses)
+      * Same API and management interface as our existing reserved IPs feature
+      * Assignable to Droplets only
+
+      BYOIP is currently in Public Preview.
+
   - name: Sizes
     description: |-
       The sizes objects represent different packages of hardware resources that
@@ -1815,6 +1827,22 @@ paths:
     post:
       $ref: "resources/reserved_ipv6/reservedIPv6Actions_post.yml"
 
+  /v2/byoip_prefixes:
+    post:
+      $ref: "resources/byoip_prefixes/byoip_prefixes_create.yml"
+    get:
+      $ref: "resources/byoip_prefixes/byoip_prefixes_list.yml"
+  
+  /v2/byoip_prefixes/{byoip_prefix_uuid}:
+    get:
+      $ref: "resources/byoip_prefixes/byoip_prefixes_get.yml"
+    delete:
+      $ref: "resources/byoip_prefixes/byoip_prefixes_delete.yml"
+  
+  /v2/byoip_prefixes/{byoip_prefix_uuid}/ips:
+    get:
+      $ref: "resources/byoip_prefixes/byoip_prefix_list_resources.yml"
+
   /v2/sizes:
     get:
       $ref: "resources/sizes/sizes_list.yml"

specification/resources/account/models/account.yml

@@ -2,12 +2,16 @@ type: object
 
 properties:
   droplet_limit:
-    description: The total number of Droplets current user or team may have active at one time.
+    description: |
+      The total number of Droplets current user or team may have active at one time.
+      <br><br>Requires `droplet:read` scope.
     type: integer
     example: 25
 
   floating_ip_limit:
-    description: The total number of Floating IPs the current user or team may have.
+    description: |
+      The total number of Floating IPs the current user or team may have.
+      <br><br>Requires `reserved_ip:read` scope.
     type: integer
     example: 5
 

specification/resources/apps/models/app.yml

@@ -61,6 +61,7 @@ properties:
     type: string
     example: 88b72d1a-b78a-4d9f-9090-b53c4399073f
     title: The ID of the project the app is assigned to. This will be empty if there is a lookup failure.
+    description: Requires `project:read` scope.
   region:
     $ref: apps_region.yml
   spec:

specification/resources/apps/models/apps_create_app_request.yml

@@ -3,7 +3,9 @@ properties:
     $ref: app_spec.yml
   project_id:
     type: string
-    description: The ID of the project the app should be assigned to. If omitted, it will be assigned to your default project.
+    description: |
+      The ID of the project the app should be assigned to. If omitted, it will be assigned to your default project.
+      <br><br>Requires `project:update` scope.
 required:
 - spec
 type: object

specification/resources/autoscale_pools/models/autoscale_pool_droplet_template.yml

@@ -43,19 +43,25 @@ properties:
       type: string
     example: 
       - "88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8"
-    description: The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint.
+    description: |
+      The SSH keys to be installed on the Droplets in the autoscale pool. You can either specify the key ID or the fingerprint.
+      Requires `ssh_key:read` scope.
   
   tags:
     type: array
     items:
       type: string
     example: 
       - my-tag
-    description: The tags to apply to each of the Droplets in the autoscale pool.
+    description: |
+      The tags to apply to each of the Droplets in the autoscale pool.
+      Requires `tag:read` scope.
   
   vpc_uuid:
     type: string
-    description: The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets.
+    description: |
+      The VPC where the Droplets in the autoscale pool will be created. The VPC must be in the region where you want to create the Droplets.
+      Requires `vpc:read` scope.
     example: 760e09ef-dc84-11e8-981e-3cfdfeaae000
 
   with_droplet_agent:
@@ -65,7 +71,9 @@ properties:
 
   project_id:
     type: string
-    description: The project that the Droplets in the autoscale pool will belong to.
+    description: |
+      The project that the Droplets in the autoscale pool will belong to.
+      Requires `project:read` scope.
     example: 746c6152-2fa2-11ed-92d3-27aaa54e4988
 
   ipv6:

specification/resources/billing/responses/invoice.yml

@@ -1,6 +1,7 @@
 description: >-
   The response will be a JSON object with a key called `invoice_items`.
-  This will be set to an array of invoice item objects.
+  This will be set to an array of invoice item objects. All resources will
+  be shown on invoices, regardless of permissions.
 
 headers:
   ratelimit-limit:
@@ -51,4 +52,4 @@ content:
             next: https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681?page=2&per_page=2
             last: https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681?page=3&per_page=2
         meta:
-          total: 6
+          total: 6

specification/resources/byoip_prefixes/byoip_prefix_list_resources.yml

@@ -0,0 +1,37 @@
+operationId: byoipPrefixes_list_resources
+
+summary: "List BYOIP Prefix Resources"
+
+description: |
+  To list resources associated with BYOIP prefixes, send a GET request to `/v2/byoip_prefixes/{byoip_prefix_uuid}/ips`.
+
+  A successful response will return a list of resources associated with the specified BYOIP prefix.
+
+tags:
+  - "[Public Preview] BYOIP Prefixes"
+
+parameters:
+  - $ref: "parameters.yml#/byoip_prefix"
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+
+responses:
+  "200":
+    $ref: "responses/byoip_prefix_list_resources.yml#/byoip_prefix_list_resources"
+  "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/byoip_prefix_list_resources.yml"
+  - $ref: "examples/go/byoip_prefix_list_resources.yml"
+  - $ref: "examples/python/byoip_prefix_list_resources.yml"
+security:
+  - bearer_auth:
+      - "byoip_prefix:read"

specification/resources/byoip_prefixes/byoip_prefixes_create.yml

@@ -0,0 +1,42 @@
+operationId: byoipPrefixes_create
+
+summary: "Create a BYOIP Prefix"
+
+description: |
+  To create a BYOIP prefix, send a POST request to `/v2/byoip_prefixes`.
+
+  A successful request will initiate the process of bringing your BYOIP Prefix into your account.
+  The response will include the details of the created prefix, including its UUID and status.
+
+tags:
+  - "[Public Preview] BYOIP Prefixes"
+
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema: 
+        $ref: "models/byoip_prefix_create.yml#/byoip_prefix_create"
+
+responses:
+  "202":
+    $ref: "responses/byoip_prefix_create.yml#/byoip_prefix_create"
+  "401":
+    $ref: "../../shared/responses/unauthorized.yml"
+  "422":
+    $ref: "../../shared/responses/unprocessable_entity.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/create_byoip_prefix.yml"
+  - $ref: "examples/go/create_byoip_prefix.yml"
+  - $ref: "examples/python/create_byoip_prefix.yml"
+
+security:
+  - bearer_auth:
+      - "byoip_prefix:create"

specification/resources/byoip_prefixes/byoip_prefixes_delete.yml

@@ -0,0 +1,41 @@
+operationId: byoipPrefixes_delete
+
+summary: "Delete a BYOIP Prefix"
+
+description: |
+  To delete a BYOIP prefix and remove it from your account, send a DELETE request
+  to `/v2/byoip_prefixes/{uuid}`.
+
+  A successful request will receive a 202 status code with no body in response.
+  This indicates that the request was accepted and the prefix is being deleted.
+
+tags:
+  - "[Public Preview] BYOIP Prefixes"
+
+parameters:
+  - $ref: "parameters.yml#/byoip_prefix"
+
+responses:
+  "202":
+    $ref: "../../shared/responses/no_content.yml"
+  "401":
+    $ref: "../../shared/responses/unauthorized.yml"
+  "404":
+    $ref: "../../shared/responses/not_found.yml"
+  "422":
+    $ref: "../../shared/responses/unprocessable_entity.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/delete_byoip_prefix.yml"
+  - $ref: "examples/go/delete_byoip_prefix.yml"
+  - $ref: "examples/python/delete_byoip_prefix.yml"
+
+security:
+  - bearer_auth:
+      - "byoip_prefix:delete"

specification/resources/byoip_prefixes/byoip_prefixes_get.yml

@@ -0,0 +1,38 @@
+operationId: byoipPrefixes_get
+
+summary: "Get a BYOIP Prefix"
+
+description: |
+  To get a BYOIP prefix, send a GET request to `/v2/byoip_prefixes/{byoip_prefix_uuid}`. 
+  
+  A successful response will return the details of the specified BYOIP prefix.
+tags:
+  - "[Public Preview] BYOIP Prefixes"
+
+parameters:
+  - $ref: "parameters.yml#/byoip_prefix"
+
+responses:
+  "200":
+    $ref: "responses/byoip_prefix_get.yml#/byoip_prefix_get"
+  "401":
+    $ref: "../../shared/responses/unauthorized.yml"
+  "404":
+    $ref: "../../shared/responses/not_found.yml"
+  "422":
+    $ref: "../../shared/responses/unprocessable_entity.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/get_byoip_prefix.yml"
+  - $ref: "examples/go/get_byoip_prefix.yml"
+  - $ref: "examples/python/get_byoip_prefix.yml"
+
+security:
+  - bearer_auth:
+      - "byoip_prefix:update"