apps: build versioning updates

specification/DigitalOcean-public.v2.yaml

@@ -651,6 +651,14 @@ paths:
     post:
       $ref: 'resources/apps/apps_revert_rollback.yml'
 
+  /v2/apps/buildpacks:
+    get:
+      $ref: 'resources/apps/apps_list_buildpacks.yml'
+
+  /v2/apps/{app_id}/upgrade_buildpack:
+    post:
+      $ref: 'resources/apps/apps_upgrade_buildpack.yml'
+
   /v2/cdn/endpoints:
     get:
       $ref: 'resources/cdn/cdn_list_endpoints.yml'

specification/resources/apps/apps_list_buildpacks.yml

@@ -0,0 +1,35 @@
+operationId: apps_list_buildpacks
+
+summary: List Buildpacks
+
+description: >-
+  List all buildpacks available on App Platform.
+
+
+  Buildpacks are one of the ways App Platform can build apps from source. For more information, see: [Builds with Buildpacks](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/).
+
+tags:
+  - Apps
+
+responses:
+  "200":
+    $ref: responses/list_buildpacks.yml
+
+  "401":
+    $ref: ../../shared/responses/unauthorized.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/apps_list_buildpacks.yml"
+
+security:
+  - bearer_auth:
+      - "read"

specification/resources/apps/apps_upgrade_buildpack.yml

@@ -0,0 +1,54 @@
+operationId: apps_upgrade_buildpack
+
+summary: Upgrade App Buildpack
+
+description: |
+  Upgrade an app's buildpack to a newer major version line.
+
+
+  The buildpack must already be part of the app's build
+  configuration. The "Retrieve an Existing App" operation will return the app's build configuration. In it, a buildpack
+  with a `latest` value of `false` indicates that an major version upgrade is available.
+
+
+  Before upgrading a buildpack, make sure to inspect its documentation page for the changelog as major version upgrades
+  are likely to introduce breaking changes to the buildpack's operation.
+
+tags:
+  - Apps
+
+parameters:
+  - $ref: parameters.yml#/app_id
+
+requestBody:
+  content:
+    application/json:
+      schema:
+        $ref: models/apps_upgrade_buildpack_request.yml
+  required: true
+
+responses:
+  "200":
+    $ref: responses/apps_upgrade_buildpack.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/apps_upgrade_buildpack.yml"
+
+security:
+  - bearer_auth:
+      - "write"

specification/resources/apps/examples/curl/apps_list_buildpacks.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/apps/buildpacks"

specification/resources/apps/examples/curl/apps_upgrade_buildpack.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{ "id": "digitalocean/node" }' \
+    "https://api.digitalocean.com/v2/apps/{app_id}/upgrade_buildpack"

specification/resources/apps/models/app.yml

@@ -74,8 +74,10 @@ properties:
     example: 2020-12-01T00:42:16Z
   pinned_deployment:
     allOf:
-      - description: The deployment that the app is pinned to.
+      - description: The deployment that the app is pinned to following a rollback.
       - $ref: apps_deployment.yml
+  build_config:
+    $ref: app_build_config.yml
 required:
-- spec
+  - spec
 type: object

specification/resources/apps/models/app_build_config.yml

@@ -0,0 +1,19 @@
+title: The app's build configuration.
+type: object
+properties:
+  cnb_versioning:
+    type: object
+    description: >-
+      Versioning configuration for Cloud Native Buildpacks-based builds.
+
+
+      Buildpacks are one of the ways App Platform can build apps from source. For more information, see:
+      [Builds with Buildpacks](https://docs.digitalocean.com/products/app-platform/reference/buildpacks/).
+    properties:
+      buildpacks:
+        type: array
+        description: >-
+          A list of versioned buildpacks used for the app's builds. Buildpacks are versioned at the major semver version
+          component, therefore exact version numbers are not available in the app's build configuration.
+        items:
+          $ref: apps_buildpack.yml

specification/resources/apps/models/apps_buildpack.yml

@@ -0,0 +1,38 @@
+properties:
+  id:
+    title: The buildpack's ID.
+    type: string
+    example: digitalocean/node
+  version:
+    title: The buildpack's version number.
+    type: string
+    format: semver
+    example: "1.2.0"
+  major_version:
+    title: The major component of the buildpack's version number. This signifies the "major version line" of the buildpack.
+    type: integer
+    format: int32
+    example: 1
+  latest:
+    title: >-
+      Indicates whether the buildpack is on the latest major version line available. A value of `false` means there is
+      another buildpack with the same ID and a newer major version.
+    type: boolean
+    example: true
+  name:
+    title: A human-friendly name.
+    type: string
+    example: Node.js
+  description:
+    items:
+      type: string
+    title: A description of the buildpack's purpose and steps performed at build time.
+    type: array
+    example:
+      - Install Node.js, NPM, and Yarn.
+      - Install dependencies using `npm ci` or `yarn install`.
+  docs_link:
+    title: A link to the buildpack's documentation.
+    type: string
+    example: https://docs.digitalocean.com/products/app-platform/reference/buildpacks/nodejs/
+type: object

specification/resources/apps/models/apps_deployment_job.yml

@@ -4,7 +4,11 @@ properties:
     type: string
     example: migrate-db
   source_commit_hash:
-    title: The commit hash of the repository that was used to build this job
+    title: The commit hash of the repository that was used to build this job if a Git source was used
     type: string
     example: 54d4a727f457231062439895000d45437c7bb405
+  source_image_digest:
+    title: The digest of the container image that was used for this job if an Image source was used
+    type: string
+    example: sha256:0285555a44f1a279ea91428ebb7ec27d2110f623739838837b070611060cd992
 type: object

specification/resources/apps/models/apps_deployment_service.yml

@@ -4,7 +4,17 @@ properties:
     type: string
     example: web
   source_commit_hash:
-    title: The commit hash of the repository that was used to build this service
+    title: The commit hash of the repository that was used to build this service if a Git source was used
     type: string
     example: 54d4a727f457231062439895000d45437c7bb405
+  source_image_digest:
+    title: The digest of the container image that was used for this service if an Image source was used
+    type: string
+    example: sha256:0285555a44f1a279ea91428ebb7ec27d2110f623739838837b070611060cd992
+  buildpacks:
+    type: array
+    items:
+      $ref: apps_buildpack.yml
+    description: >-
+      The list of buildpacks used to build this component. The buildpacks' full version numbers are included.
 type: object

specification/resources/apps/models/apps_deployment_static_site.yml

@@ -7,4 +7,10 @@ properties:
     title: The commit hash of the repository that was used to build this static site
     type: string
     example: 54d4a727f457231062439895000d45437c7bb405
+  buildpacks:
+    type: array
+    items:
+      $ref: apps_buildpack.yml
+    description: >-
+      The list of buildpacks used to build this component. The buildpacks' full version numbers are included.
 type: object

specification/resources/apps/models/apps_deployment_worker.yml

@@ -4,7 +4,11 @@ properties:
     type: string
     example: queue-runner
   source_commit_hash:
-    title: The commit hash of the repository that was used to build this worker
+    title: The commit hash of the repository that was used to build this worker if a Git source was used
     type: string
     example: 54d4a727f457231062439895000d45437c7bb405
+  source_image_digest:
+    title: The digest of the container image that was used for this worker if an Image source was used
+    type: string
+    example: sha256:0285555a44f1a279ea91428ebb7ec27d2110f623739838837b070611060cd992
 type: object

specification/resources/apps/models/apps_list_buildpacks_response.yml

@@ -0,0 +1,6 @@
+properties:
+  buildpacks:
+    items:
+      $ref: apps_buildpack.yml
+    type: array
+type: object

specification/resources/apps/models/apps_upgrade_buildpack_request.yml

@@ -0,0 +1,22 @@
+type: object
+properties:
+  buildpack_id:
+    type: string
+    description: The ID of the buildpack to upgrade.
+    example: digitalocean/node
+  major_version:
+    type: integer
+    format: int32
+    description: >-
+      The major version line to upgrade the buildpack to. If omitted, the latest available major version line will be
+      used.
+    example: 2
+  trigger_deployment:
+    type: boolean
+    description: >-
+      Whether to trigger a new app deployment to apply the buildpack upgrade. If `false`, the upgrade will be applied by
+      the next app deployment.
+    default: true
+    example: true
+required:
+  - buildpack_id

specification/resources/apps/responses/apps_upgrade_buildpack.yml

@@ -0,0 +1,34 @@
+description: A JSON object with the upgrade results.
+
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        affected_components:
+          type: array
+          description: Contains a list of components affected by the buildpack upgrade.
+          items:
+            type: string
+          example:
+            - component name
+        deployment:
+          allOf:
+            - description: >-
+                The new deployment that was created for the buildpack upgrade if `trigger_deployment` was
+                specified in the request.
+            - $ref: ../models/apps_deployment.yml
+    examples:
+      Request with `trigger_deployment` set to `false`:
+        value:
+          affected_components:
+            - api
+            - frontend
+
+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