From 0fb99b0fa67096437b112d71e48675d764c1b0c2 Mon Sep 17 00:00:00 2001 From: Sam Gunaratne Date: Wed, 10 Sep 2025 11:21:02 -0600 Subject: [PATCH 01/14] Add missing set role by username feature --- .../components/requestBodies/RoleCreate.yaml | 3 +- apis/cf/latest/components/schemas/Role.yaml | 2 +- .../schemas/UserRelationshipToOne.yaml | 31 +++++++++++++++++++ apis/cf/latest/openapi.yaml | 5 ++- 4 files changed, 37 insertions(+), 4 deletions(-) create mode 100644 apis/cf/latest/components/schemas/UserRelationshipToOne.yaml diff --git a/apis/cf/latest/components/requestBodies/RoleCreate.yaml b/apis/cf/latest/components/requestBodies/RoleCreate.yaml index 4c7b997..29abf2e 100644 --- a/apis/cf/latest/components/requestBodies/RoleCreate.yaml +++ b/apis/cf/latest/components/requestBodies/RoleCreate.yaml @@ -20,8 +20,7 @@ content: type: object properties: user: - $ref: '../schemas/RelationshipToOne.yaml' - description: A relationship to a user; the user can be defined by either a `guid` or, if the `set_roles_by_username` [feature_flag](#list-of-feature-flags) is enabled, a `username` (with the option of including an `origin` to disambiguate it) + $ref: '../schemas/UserRelationshipToOne.yaml' organization: $ref: '../schemas/RelationshipToOne.yaml' description: A relationship to an organization; required only when creating an organization role diff --git a/apis/cf/latest/components/schemas/Role.yaml b/apis/cf/latest/components/schemas/Role.yaml index fcbb6ed..f49bb3e 100644 --- a/apis/cf/latest/components/schemas/Role.yaml +++ b/apis/cf/latest/components/schemas/Role.yaml @@ -39,7 +39,7 @@ properties: A relationship to the space the role controls access to; when this is an organization role, `space.data` will be `null`. user: allOf: - - $ref: './RelationshipToOne.yaml' + - $ref: './UserRelationshipToOne.yaml' - description: | A relationship to the user; this is the user that has the role links: diff --git a/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml b/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml new file mode 100644 index 0000000..0cb4c8b --- /dev/null +++ b/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml @@ -0,0 +1,31 @@ +type: [object, "null"] +properties: + data: + type: object + description: | + User relationship data that can be specified either by GUID or by username and origin. + When using username and origin, the set_roles_by_username feature flag must be enabled. + oneOf: + - type: object + properties: + guid: + type: string + format: uuid + description: The GUID of the user + required: + - guid + additionalProperties: false + - type: object + properties: + username: + type: string + description: The username of the user + origin: + type: string + description: The identity provider for the user (e.g., 'ldap', 'saml'). Optional field to disambiguate the username. + required: + - username + additionalProperties: false + description: | + User relationship data that can be specified either by GUID or by username and origin. + Set to null to clear the relationship. \ No newline at end of file diff --git a/apis/cf/latest/openapi.yaml b/apis/cf/latest/openapi.yaml index 296df2c..6a87a2a 100644 --- a/apis/cf/latest/openapi.yaml +++ b/apis/cf/latest/openapi.yaml @@ -107,7 +107,10 @@ components: $ref: './components/schemas/RelationshipToOne.yaml' RelationshipToMany: $ref: './components/schemas/RelationshipToMany.yaml' - + UserRelationshipToOne: + $ref: './components/schemas/UserRelationshipToOne.yaml' + IncludedResources: + $ref: './components/schemas/IncludedResources.yaml' Link: $ref: './components/schemas/Link.yaml' Pagination: From 338ce3e2b4fb5c5ab4dfdea83ee1b39df003f15e Mon Sep 17 00:00:00 2001 From: Florian Braun <5863788+FloThinksPi@users.noreply.github.com> Date: Mon, 22 Sep 2025 11:40:05 +0200 Subject: [PATCH 02/14] Flag spec as experimental --- apis/cf/latest/openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/cf/latest/openapi.yaml b/apis/cf/latest/openapi.yaml index 6a87a2a..7da5fbc 100644 --- a/apis/cf/latest/openapi.yaml +++ b/apis/cf/latest/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Cloud Foundry V3 API - description: "# Welcome to the Cloud Foundry V3 API docs! This is the latest available specification. \n\n# Getting help\nThe CAPI team can most easily be reached on our Slack channel for questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub issue on our API repo, cloud_controller_ng.\nWe recommend reaching out to Slack first as we will be most responsive there.\n \n# More resources\n- The Cloud Foundry V2 API is still deprecated but still available for interacting with Cloud Foundry.\n- Running Tasks\n- V3 API Documentation OpenAPI Spec Source Code. " + description: "# Welcome to the Experimental Cloud Foundry V3 API Docs! \n\n# Expermiental Warning\n This OpenAPI specification is a experiment and not ready for productive use.\n# Getting help\nThe CAPI team can most easily be reached on our Slack channel for questions and issues regarding the API. To report an issue with the docs or API, please feel free to file a GitHub issue on our API repo, cloud_controller_ng.\nWe recommend reaching out to Slack first as we will be most responsive there.\n \n# More resources\n- The Cloud Foundry V2 API is still deprecated but still available for interacting with Cloud Foundry.\n- Running Tasks\n- V3 API Documentation OpenAPI Spec Source Code. " version: latest license: name: Apache 2.0 From 9bf98386c5ad443047a5387068b3752a34d3f778 Mon Sep 17 00:00:00 2001 From: pl018383 Date: Fri, 31 Oct 2025 11:41:26 -0400 Subject: [PATCH 03/14] Fix list resources Add role resources schema as included will not be returned in role list responses. Update organization list to include pagination as a property Update users path ti use user list as paginatedusers contains extra properties not returned from the api --- .../responses/RoleListResponse.yaml | 2 +- .../components/schemas/OrganizationList.yaml | 14 ++--- .../components/schemas/RoleResources.yaml | 63 +++++++++++++++++++ apis/cf/latest/paths/Users.yaml | 2 +- 4 files changed, 72 insertions(+), 9 deletions(-) create mode 100644 apis/cf/latest/components/schemas/RoleResources.yaml diff --git a/apis/cf/latest/components/responses/RoleListResponse.yaml b/apis/cf/latest/components/responses/RoleListResponse.yaml index fb8b083..1d14c42 100644 --- a/apis/cf/latest/components/responses/RoleListResponse.yaml +++ b/apis/cf/latest/components/responses/RoleListResponse.yaml @@ -9,7 +9,7 @@ content: resources: type: array items: - $ref: '../schemas/Role.yaml' + $ref: '../schemas/RoleResources.yaml' included: $ref: '../schemas/IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/apis/cf/latest/components/schemas/OrganizationList.yaml b/apis/cf/latest/components/schemas/OrganizationList.yaml index e8f28da..f23e060 100644 --- a/apis/cf/latest/components/schemas/OrganizationList.yaml +++ b/apis/cf/latest/components/schemas/OrganizationList.yaml @@ -1,9 +1,9 @@ type: object -allOf: - - $ref: './Pagination.yaml' - - properties: - resources: - type: array - items: - $ref: './Organization.yaml' +properties: + pagination: + $ref: './Pagination.yaml' + resources: + type: array + items: + $ref: './Organization.yaml' description: A paginated list of organizations diff --git a/apis/cf/latest/components/schemas/RoleResources.yaml b/apis/cf/latest/components/schemas/RoleResources.yaml new file mode 100644 index 0000000..be4b6cd --- /dev/null +++ b/apis/cf/latest/components/schemas/RoleResources.yaml @@ -0,0 +1,63 @@ +allOf: + - $ref: './BaseSchema.yaml' +type: object +properties: + type: + type: string + description: |- + Role type. Possible values are: + - `organization_user`: A user in the organization + - `organization_auditor`: An auditor in the organization + - `organization_manager`: A manager in the organization + - `organization_billing_manager`: A billing manager in the organization + - `space_auditor`: An auditor in the space + - `space_developer`: A developer in the space + - `space_manager`: A manager in the space + - `space_supporter`: A supporter in the space (not authorized to use the V2 API) + enum: + - organization_user + - organization_auditor + - organization_manager + - organization_billing_manager + - space_auditor + - space_developer + - space_manager + - space_supporter + relationships: + allOf: + - $ref: './Relationships.yaml' + properties: + organization: + allOf: + - $ref: './RelationshipToOne.yaml' + - description: | + A relationship to the organization the role controls access to; when this is a space role, `organization.data` will be `null`. + space: + allOf: + - $ref: './RelationshipToOne.yaml' + - description: | + A relationship to the space the role controls access to; when this is an organization role, `space.data` will be `null`. + user: + allOf: + - $ref: './UserRelationshipToOne.yaml' + - description: | + A relationship to the user; this is the user that has the role + links: + type: object + properties: + self: + $ref: './Link.yaml' + description: The URL to get this role + user: + $ref: './Link.yaml' + description: The URL to get the user for this role + organization: + $ref: './Link.yaml' + description: The URL to get the organization for this role + space: + $ref: './Link.yaml' + description: The URL to get the space for this role +description: | + Roles represent a set of permissions that can be granted to users. Roles are represented as a JSON object. + A role consists of several required role fields and other attributes specific to the role. + See Roles for specific roles. diff --git a/apis/cf/latest/paths/Users.yaml b/apis/cf/latest/paths/Users.yaml index b46f92d..904fe87 100644 --- a/apis/cf/latest/paths/Users.yaml +++ b/apis/cf/latest/paths/Users.yaml @@ -46,7 +46,7 @@ content: application/json: schema: - $ref: '../components/schemas/PaginatedUsers.yaml' + $ref: '../components/schemas/UserList.yaml' '400': $ref: '../components/responses/BadRequest.yaml' '401': From ef0794527c7ecd0d24c88314079287432910ccea Mon Sep 17 00:00:00 2001 From: pl018383 Date: Fri, 31 Oct 2025 13:20:34 -0400 Subject: [PATCH 04/14] Adjust App List to not include Included within Resources array --- .../cf/latest/components/schemas/AppList.yaml | 2 +- .../components/schemas/AppResources.yaml | 46 +++++++++++++++++++ 2 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 apis/cf/latest/components/schemas/AppResources.yaml diff --git a/apis/cf/latest/components/schemas/AppList.yaml b/apis/cf/latest/components/schemas/AppList.yaml index dcd3ea8..0615034 100644 --- a/apis/cf/latest/components/schemas/AppList.yaml +++ b/apis/cf/latest/components/schemas/AppList.yaml @@ -5,7 +5,7 @@ properties: resources: type: array items: - $ref: './App.yaml' + $ref: './AppResources.yaml' included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/apis/cf/latest/components/schemas/AppResources.yaml b/apis/cf/latest/components/schemas/AppResources.yaml new file mode 100644 index 0000000..4c40eeb --- /dev/null +++ b/apis/cf/latest/components/schemas/AppResources.yaml @@ -0,0 +1,46 @@ +type: object +allOf: + - $ref: './BaseSchema.yaml' + - properties: + name: + type: string + description: The name of the app + state: + type: string + description: Current desired state of the app + enum: + - STOPPED + - STARTED + lifecycle: + $ref: './Lifecycle.yaml' + description: Provides the default lifecycle object for the application. This lifecycle will be used when staging and running the application. The staging lifecycle can be overridden on builds + relationships: + $ref: './Relationships.yaml' + metadata: + $ref: './Metadata.yaml' + links: + type: object + properties: + self: + $ref: './Link.yaml' + description: The URL to get this app + space: + $ref: './Link.yaml' + description: The URL to get the space for this app + processes: + $ref: './Link.yaml' + description: The URL to get the processes for this app + packages: + $ref: './Link.yaml' + description: The URL to get the packages for this app + environment_variables: + $ref: './Link.yaml' + description: The URL to get the environment variables for this app + current_droplet: + $ref: './Link.yaml' + description: The URL to get the current droplet for this app + droplets: + $ref: './Link.yaml' + description: The URL to get the droplets for this app +description: > + Apps represent the core entities in the Cloud Foundry environment. They are the deployable units that run your code. Each app can have multiple processes, routes, and services associated with it. Apps can be scaled horizontally by increasing the number of instances. They can also be updated and restarted as needed. From d2089f96a656a05915a46a3bac295d7428e5bc39 Mon Sep 17 00:00:00 2001 From: pl018383 Date: Mon, 10 Nov 2025 11:13:31 -0500 Subject: [PATCH 05/14] Remove unused PaginatedUsers component schema --- apis/cf/latest/components/schemas/PaginatedUsers.yaml | 10 ---------- apis/cf/latest/openapi.yaml | 2 -- 2 files changed, 12 deletions(-) delete mode 100644 apis/cf/latest/components/schemas/PaginatedUsers.yaml diff --git a/apis/cf/latest/components/schemas/PaginatedUsers.yaml b/apis/cf/latest/components/schemas/PaginatedUsers.yaml deleted file mode 100644 index 5fac46b..0000000 --- a/apis/cf/latest/components/schemas/PaginatedUsers.yaml +++ /dev/null @@ -1,10 +0,0 @@ -allOf: - - $ref: './BaseSchema.yaml' - - type: object - properties: - pagination: - $ref: './Pagination.yaml' - resources: - type: array - items: - $ref: './User.yaml' diff --git a/apis/cf/latest/openapi.yaml b/apis/cf/latest/openapi.yaml index 7da5fbc..21001f6 100644 --- a/apis/cf/latest/openapi.yaml +++ b/apis/cf/latest/openapi.yaml @@ -123,8 +123,6 @@ components: $ref: './components/schemas/BuildpackList.yaml' User: $ref: './components/schemas/User.yaml' - PaginatedUsers: - $ref: './components/schemas/PaginatedUsers.yaml' Droplet: $ref: './components/schemas/Droplet.yaml' DropletList: From 6bba909f1a73f79f97af7a1694fc72ea02fe0189 Mon Sep 17 00:00:00 2001 From: pl018383 Date: Wed, 19 Nov 2025 11:12:48 -0500 Subject: [PATCH 06/14] Update Resources Reference for Included Field --- .../responses/RoleListResponse.yaml | 2 +- .../cf/latest/components/schemas/AppList.yaml | 2 +- .../components/schemas/AppResources.yaml | 46 -------------- .../components/schemas/RoleResources.yaml | 63 ------------------- 4 files changed, 2 insertions(+), 111 deletions(-) delete mode 100644 apis/cf/latest/components/schemas/AppResources.yaml delete mode 100644 apis/cf/latest/components/schemas/RoleResources.yaml diff --git a/apis/cf/latest/components/responses/RoleListResponse.yaml b/apis/cf/latest/components/responses/RoleListResponse.yaml index 1d14c42..fb8b083 100644 --- a/apis/cf/latest/components/responses/RoleListResponse.yaml +++ b/apis/cf/latest/components/responses/RoleListResponse.yaml @@ -9,7 +9,7 @@ content: resources: type: array items: - $ref: '../schemas/RoleResources.yaml' + $ref: '../schemas/Role.yaml' included: $ref: '../schemas/IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/apis/cf/latest/components/schemas/AppList.yaml b/apis/cf/latest/components/schemas/AppList.yaml index 0615034..dcd3ea8 100644 --- a/apis/cf/latest/components/schemas/AppList.yaml +++ b/apis/cf/latest/components/schemas/AppList.yaml @@ -5,7 +5,7 @@ properties: resources: type: array items: - $ref: './AppResources.yaml' + $ref: './App.yaml' included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/apis/cf/latest/components/schemas/AppResources.yaml b/apis/cf/latest/components/schemas/AppResources.yaml deleted file mode 100644 index 4c40eeb..0000000 --- a/apis/cf/latest/components/schemas/AppResources.yaml +++ /dev/null @@ -1,46 +0,0 @@ -type: object -allOf: - - $ref: './BaseSchema.yaml' - - properties: - name: - type: string - description: The name of the app - state: - type: string - description: Current desired state of the app - enum: - - STOPPED - - STARTED - lifecycle: - $ref: './Lifecycle.yaml' - description: Provides the default lifecycle object for the application. This lifecycle will be used when staging and running the application. The staging lifecycle can be overridden on builds - relationships: - $ref: './Relationships.yaml' - metadata: - $ref: './Metadata.yaml' - links: - type: object - properties: - self: - $ref: './Link.yaml' - description: The URL to get this app - space: - $ref: './Link.yaml' - description: The URL to get the space for this app - processes: - $ref: './Link.yaml' - description: The URL to get the processes for this app - packages: - $ref: './Link.yaml' - description: The URL to get the packages for this app - environment_variables: - $ref: './Link.yaml' - description: The URL to get the environment variables for this app - current_droplet: - $ref: './Link.yaml' - description: The URL to get the current droplet for this app - droplets: - $ref: './Link.yaml' - description: The URL to get the droplets for this app -description: > - Apps represent the core entities in the Cloud Foundry environment. They are the deployable units that run your code. Each app can have multiple processes, routes, and services associated with it. Apps can be scaled horizontally by increasing the number of instances. They can also be updated and restarted as needed. diff --git a/apis/cf/latest/components/schemas/RoleResources.yaml b/apis/cf/latest/components/schemas/RoleResources.yaml deleted file mode 100644 index be4b6cd..0000000 --- a/apis/cf/latest/components/schemas/RoleResources.yaml +++ /dev/null @@ -1,63 +0,0 @@ -allOf: - - $ref: './BaseSchema.yaml' -type: object -properties: - type: - type: string - description: |- - Role type. Possible values are: - - `organization_user`: A user in the organization - - `organization_auditor`: An auditor in the organization - - `organization_manager`: A manager in the organization - - `organization_billing_manager`: A billing manager in the organization - - `space_auditor`: An auditor in the space - - `space_developer`: A developer in the space - - `space_manager`: A manager in the space - - `space_supporter`: A supporter in the space (not authorized to use the V2 API) - enum: - - organization_user - - organization_auditor - - organization_manager - - organization_billing_manager - - space_auditor - - space_developer - - space_manager - - space_supporter - relationships: - allOf: - - $ref: './Relationships.yaml' - properties: - organization: - allOf: - - $ref: './RelationshipToOne.yaml' - - description: | - A relationship to the organization the role controls access to; when this is a space role, `organization.data` will be `null`. - space: - allOf: - - $ref: './RelationshipToOne.yaml' - - description: | - A relationship to the space the role controls access to; when this is an organization role, `space.data` will be `null`. - user: - allOf: - - $ref: './UserRelationshipToOne.yaml' - - description: | - A relationship to the user; this is the user that has the role - links: - type: object - properties: - self: - $ref: './Link.yaml' - description: The URL to get this role - user: - $ref: './Link.yaml' - description: The URL to get the user for this role - organization: - $ref: './Link.yaml' - description: The URL to get the organization for this role - space: - $ref: './Link.yaml' - description: The URL to get the space for this role -description: | - Roles represent a set of permissions that can be granted to users. Roles are represented as a JSON object. - A role consists of several required role fields and other attributes specific to the role. - See Roles for specific roles. From 8cb513cca36aa4d778a42edc3459139d8f763208 Mon Sep 17 00:00:00 2001 From: Sam Gunaratne Date: Tue, 6 Jan 2026 09:37:03 -0700 Subject: [PATCH 07/14] User guids can be client ids --- .../components/parameters/UserGuid.yaml | 6 +++ apis/cf/latest/components/schemas/User.yaml | 49 +++++++++++-------- .../schemas/UserRelationshipToOne.yaml | 3 +- apis/cf/latest/paths/Users.yaml | 10 ++-- 4 files changed, 41 insertions(+), 27 deletions(-) create mode 100644 apis/cf/latest/components/parameters/UserGuid.yaml diff --git a/apis/cf/latest/components/parameters/UserGuid.yaml b/apis/cf/latest/components/parameters/UserGuid.yaml new file mode 100644 index 0000000..3de29c3 --- /dev/null +++ b/apis/cf/latest/components/parameters/UserGuid.yaml @@ -0,0 +1,6 @@ +name: guid +in: path +required: true +schema: + type: string +description: The unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid. diff --git a/apis/cf/latest/components/schemas/User.yaml b/apis/cf/latest/components/schemas/User.yaml index 5c9414e..6252481 100644 --- a/apis/cf/latest/components/schemas/User.yaml +++ b/apis/cf/latest/components/schemas/User.yaml @@ -1,21 +1,30 @@ type: object -allOf: - - $ref: './BaseSchema.yaml' - - properties: - username: - type: [string, "null"] - description: The username of the user - presentation_name: - type: string - description: The presentation name of the user - origin: - type: [string, "null"] - description: The origin of the user - metadata: - $ref: './Metadata.yaml' - links: - type: object - properties: - self: - $ref: './Link.yaml' - description: The URL to get this user \ No newline at end of file +properties: + guid: + type: string + description: Unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid. + created_at: + type: string + format: date-time + description: The ISO8601 compatible date and time when resource was created + updated_at: + type: string + format: date-time + description: The ISO8601 compatible date and time when resource was last updated + username: + type: [string, "null"] + description: The username of the user + presentation_name: + type: string + description: The presentation name of the user + origin: + type: [string, "null"] + description: The origin of the user + metadata: + $ref: './Metadata.yaml' + links: + type: object + properties: + self: + $ref: './Link.yaml' + description: The URL to get this user \ No newline at end of file diff --git a/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml b/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml index 0cb4c8b..12e2fef 100644 --- a/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml +++ b/apis/cf/latest/components/schemas/UserRelationshipToOne.yaml @@ -10,8 +10,7 @@ properties: properties: guid: type: string - format: uuid - description: The GUID of the user + description: The GUID of the user, matching either a UAA user id or client id. A client id may not be a uuid. required: - guid additionalProperties: false diff --git a/apis/cf/latest/paths/Users.yaml b/apis/cf/latest/paths/Users.yaml index 904fe87..f844746 100644 --- a/apis/cf/latest/paths/Users.yaml +++ b/apis/cf/latest/paths/Users.yaml @@ -18,7 +18,7 @@ type: array items: type: string - description: Comma-delimited list of user guids to filter by + description: Comma-delimited list of user guids to filter by (can include UAA user IDs or client IDs) - name: usernames in: query schema: @@ -111,7 +111,7 @@ tags: - Users parameters: - - $ref: '../components/parameters/Guid.yaml' + - $ref: '../components/parameters/UserGuid.yaml' responses: '200': description: OK @@ -127,12 +127,12 @@ $ref: '../components/responses/Forbidden.yaml' patch: summary: Update a user - description: Update a user’s metadata. + description: Update a user's metadata. operationId: updateUser tags: - Users parameters: - - $ref: '../components/parameters/Guid.yaml' + - $ref: '../components/parameters/UserGuid.yaml' requestBody: $ref: '../components/requestBodies/UserUpdate.yaml' responses: @@ -161,7 +161,7 @@ tags: - Users parameters: - - $ref: '../components/parameters/Guid.yaml' + - $ref: '../components/parameters/UserGuid.yaml' responses: '202': description: Accepted From 2b2187550de37575fd301227cdbc1758600440b3 Mon Sep 17 00:00:00 2001 From: Mervin Nirmal John MW Date: Wed, 21 Jan 2026 22:21:51 +0530 Subject: [PATCH 08/14] Update openapi schema changes of Deployment and Processes (#1044) * Update openapi schema changes of Deployment and Processes * Update apis/cf/latest/components/schemas/Deployment.yaml * Update apis/cf/latest/paths/Deployments.yaml * Update apis/cf/latest/paths/Deployments.yaml --------- Co-authored-by: Sam Gunaratne <385176+Samze@users.noreply.github.com> --- .../latest/components/schemas/Deployment.yaml | 25 ++++++++++++++ apis/cf/latest/paths/Deployments.yaml | 33 +++++++++++++++++++ apis/cf/latest/paths/Processes.yaml | 14 ++++---- 3 files changed, 66 insertions(+), 6 deletions(-) diff --git a/apis/cf/latest/components/schemas/Deployment.yaml b/apis/cf/latest/components/schemas/Deployment.yaml index 3261efe..fb28d35 100644 --- a/apis/cf/latest/components/schemas/Deployment.yaml +++ b/apis/cf/latest/components/schemas/Deployment.yaml @@ -44,6 +44,31 @@ allOf: max_in_flight: type: integer description: The maximum number of new instances to deploy simultaneously + web_instances: + type: integer + description: The number of instances for the web process of the new droplet + memory_in_mb: + type: integer + description: The amount of memory in megabytes to allocate for the web process + disk_in_mb: + type: integer + description: The amount of disk space in megabytes to allocate for the web process + log_rate_limit_in_bytes_per_second: + type: integer + description: The log rate limit in bytes per second for the web process. A value of -1 indicates unlimited, 0 prevents any logs from being emitted. + canary: + type: object + description: Configuration for canary deployments. Present when strategy is 'canary'. + properties: + steps: + type: array + description: Array of steps defining the canary deployment progression + items: + type: object + properties: + instance_weight: + type: integer + description: The percentage of instances to be deployed as part of the canary process in this step droplet: type: object properties: diff --git a/apis/cf/latest/paths/Deployments.yaml b/apis/cf/latest/paths/Deployments.yaml index b27b47b..40fcc47 100644 --- a/apis/cf/latest/paths/Deployments.yaml +++ b/apis/cf/latest/paths/Deployments.yaml @@ -96,6 +96,39 @@ enum: - rolling - canary + options: + type: object + properties: + max_in_flight: + type: integer + description: The maximum number of instances that will be deployed simultaneously + default: 1 + minimum: 1 + web_instances: + type: integer + description: The number of instances for the web process of the new droplet + memory_in_mb: + type: integer + description: The amount of memory in megabytes to allocate for the web process + disk_in_mb: + type: integer + description: The amount of disk space in megabytes to allocate for the web process + log_rate_limit_in_bytes_per_second: + type: integer + description: The log rate limit in bytes per second for the web process. A value of -1 indicates unlimited, 0 prevents any logs from being emitted. + canary: + type: object + description: Canary steps to use for the deployment. Only available for deployments with strategy ‘canary’. + properties: + steps: + type: array + description: Array of steps defining the canary deployment progression + items: + type: object + properties: + instance_weight: + type: integer + description: The percentage of instances to be deployed as part of the canary process in this step droplet: $ref: '../components/schemas/Relationship.yaml' revision: diff --git a/apis/cf/latest/paths/Processes.yaml b/apis/cf/latest/paths/Processes.yaml index 1cddf91..bc8e41b 100644 --- a/apis/cf/latest/paths/Processes.yaml +++ b/apis/cf/latest/paths/Processes.yaml @@ -189,22 +189,22 @@ type: - integer - 'null' - - string + description: The number of instances to run memory_in_mb: type: - integer - 'null' - - string + description: The memory in MB allocated per instance disk_in_mb: type: - integer - 'null' - - string + description: The disk in MB allocated per instance log_rate_limit_in_bytes_per_second: type: - integer - 'null' - - string + description: The log rate limit in bytes per second per instance responses: '202': description: Accepted @@ -395,20 +395,22 @@ type: - integer - 'null' - - string + description: The number of instances to run memory_in_mb: type: - integer - 'null' - - string + description: The memory in MB allocated per instance disk_in_mb: type: - integer - 'null' + description: The disk in MB allocated per instance log_rate_limit_in_bytes_per_second: type: - integer - 'null' + description: The log rate limit in bytes per second per instance responses: '202': description: Accepted From 70c07ec39b767dba5e58f4bc999558790a634ec7 Mon Sep 17 00:00:00 2001 From: Sameer Chandra Date: Tue, 31 Mar 2026 23:20:51 +0530 Subject: [PATCH 09/14] Fix incorrect JSON pointer path for droplet GUID in Builds.yaml (#1045) The OpenAPI link for retrieving the droplet was using the path $response.body#/droplet/data/guid, but the actual REST response structure has the GUID directly under droplet: "droplet": { "guid": "..." } Changed the path to $response.body#/droplet/guid to match the actual API response. --- apis/cf/latest/paths/Builds.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/cf/latest/paths/Builds.yaml b/apis/cf/latest/paths/Builds.yaml index bd3dd3a..54848a8 100644 --- a/apis/cf/latest/paths/Builds.yaml +++ b/apis/cf/latest/paths/Builds.yaml @@ -145,7 +145,7 @@ droplet: operationId: getDroplet parameters: - guid: $response.body#/droplet/data/guid + guid: $response.body#/droplet/guid description: Retrieve the droplet for this build '401': $ref: '../components/responses/Unauthorized.yaml' From 539f64623a4337939c2e9f4511485eadde50fc56 Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Thu, 23 Apr 2026 13:51:44 -0700 Subject: [PATCH 10/14] Remove non-existent PUT method from /v3/routes/{guid}/destinations (#1050) CCNG routes.rb only defines PATCH for replacing route destinations (routes#replace_destinations). The PUT method documented in the spec does not correspond to any route in cloud_controller_ng and would result in a 404 if called. The PATCH method (operationId: replaceDestinationsForRouteWithPatch) remains and is the correct way to replace destinations. Made-with: Cursor --- apis/cf/latest/paths/Routes.yaml | 39 -------------------------------- 1 file changed, 39 deletions(-) diff --git a/apis/cf/latest/paths/Routes.yaml b/apis/cf/latest/paths/Routes.yaml index e336a13..48466b4 100644 --- a/apis/cf/latest/paths/Routes.yaml +++ b/apis/cf/latest/paths/Routes.yaml @@ -534,45 +534,6 @@ $ref: '../components/responses/UnprocessableEntity.yaml' '404': $ref: '../components/responses/NotFound.yaml' - put: - summary: Replace all destinations for a route - description: 'Replaces all destinations for a route, removing any destinations - not included in the provided list. - - - Weighted destinations are **deprecated**. Development of the experimental Istio - Service Mesh routing layer was discontinued in 2020 and is no longer supported - by the platform. Specifying a `weight` for a destination will take no effect. - - - If weighted destinations are provided, however, all destinations provided here - must have a `weight` specified, and all weights for this route must sum to 100. - If not, all provided destinations must not have a `weight`. Mixing weighted - and unweighted destinations for a route is not allowed.' - operationId: replaceDestinationsForRoute - tags: - - Routes - parameters: - - $ref: '../components/parameters/Guid.yaml' - requestBody: - $ref: '../components/requestBodies/RouteDestinations.yaml' - responses: - '200': - description: List of destinations for the route - content: - application/json: - schema: - $ref: '../components/schemas/RouteDestinationList.yaml' - '400': - $ref: '../components/responses/BadRequest.yaml' - '401': - $ref: '../components/responses/Unauthorized.yaml' - '403': - $ref: '../components/responses/Forbidden.yaml' - '422': - $ref: '../components/responses/UnprocessableEntity.yaml' - '500': - $ref: '../components/responses/500.yaml' /v3/routes/{guid}/destinations/{destination_guid}: patch: summary: Update a destination protocol for a route From adf6eb87346ef94bf61253d80a71619280b75bbb Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Thu, 23 Apr 2026 14:01:56 -0700 Subject: [PATCH 11/14] Add GET /v3/processes/{guid}/process_instances endpoint to spec (#1049) This endpoint exists in CCNG routes.rb and returns a simplified view of process instances (index, state, since) compared to the /stats endpoint which returns detailed resource usage. Added the path definition to Processes.yaml and wired it into openapi.yaml. Made-with: Cursor --- apis/cf/latest/openapi.yaml | 2 ++ apis/cf/latest/paths/Processes.yaml | 49 +++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/apis/cf/latest/openapi.yaml b/apis/cf/latest/openapi.yaml index 21001f6..05bce24 100644 --- a/apis/cf/latest/openapi.yaml +++ b/apis/cf/latest/openapi.yaml @@ -606,6 +606,8 @@ paths: $ref: './paths/Processes.yaml#/~1v3~1processes' /v3/processes/{guid}: $ref: './paths/Processes.yaml#/~1v3~1processes~1{guid}' + /v3/processes/{guid}/process_instances: + $ref: './paths/Processes.yaml#/~1v3~1processes~1{guid}~1process_instances' /v3/processes/{guid}/stats: $ref: './paths/Processes.yaml#/~1v3~1processes~1{guid}~1stats' /v3/processes/{guid}/actions/scale: diff --git a/apis/cf/latest/paths/Processes.yaml b/apis/cf/latest/paths/Processes.yaml index bc8e41b..4150940 100644 --- a/apis/cf/latest/paths/Processes.yaml +++ b/apis/cf/latest/paths/Processes.yaml @@ -147,6 +147,55 @@ $ref: '../components/responses/ServiceUnavailable.yaml' '409': $ref: '../components/responses/Conflict.yaml' +/v3/processes/{guid}/process_instances: + get: + summary: List instances for a process + description: Retrieve the instances for a process. Unlike the stats endpoint, + this returns a simplified view with only the index, state, and uptime of each + instance. + operationId: listProcessInstances + tags: + - Processes + parameters: + - $ref: '../components/parameters/Guid.yaml' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resources: + type: array + items: + type: object + properties: + index: + type: integer + state: + type: string + enum: + - RUNNING + - CRASHED + - STARTING + - DOWN + since: + type: number + format: double + links: + type: object + properties: + self: + $ref: '../components/schemas/Link.yaml' + process: + $ref: '../components/schemas/Link.yaml' + '401': + $ref: '../components/responses/Unauthorized.yaml' + '404': + $ref: '../components/responses/NotFound.yaml' + '403': + $ref: '../components/responses/Forbidden.yaml' /v3/processes/{guid}/stats: get: summary: Get stats for a process From b3c16a73746382e1901253da179f9ac918d5cbe7 Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Thu, 23 Apr 2026 14:02:44 -0700 Subject: [PATCH 12/14] Add missing endpoint specs for spaces usage_summary and isolation segment organizations (#1048) Two endpoints exist in cloud_controller_ng routes.rb but were missing from the OpenAPI specification: 1. GET /v3/spaces/{guid}/usage_summary - public endpoint analogous to the already-documented GET /v3/organizations/{guid}/usage_summary. Added path definition to Spaces.yaml and wired into openapi.yaml. 2. GET /v3/isolation_segments/{guid}/organizations - path definition already existed in IsolationSegments.yaml but was not referenced from openapi.yaml paths section. Added the $ref to make it visible to spec consumers. Made-with: Cursor --- apis/cf/latest/openapi.yaml | 4 +++ apis/cf/latest/paths/Spaces.yaml | 52 ++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/apis/cf/latest/openapi.yaml b/apis/cf/latest/openapi.yaml index 05bce24..dcd3c9c 100644 --- a/apis/cf/latest/openapi.yaml +++ b/apis/cf/latest/openapi.yaml @@ -446,6 +446,8 @@ paths: $ref: './paths/IsolationSegments.yaml#/~1v3~1isolation_segments~1{guid}~1relationships~1organizations~1{org_guid}' /v3/isolation_segments/{guid}/relationships/spaces: $ref: './paths/IsolationSegments.yaml#/~1v3~1isolation_segments~1{guid}~1relationships~1spaces' + /v3/isolation_segments/{guid}/organizations: + $ref: './paths/IsolationSegments.yaml#/~1v3~1isolation_segments~1{guid}~1organizations' /v3/jobs/{guid}: $ref: './paths/Jobs.yaml#/~1v3~1jobs~1{guid}' /v3/resource_matches: @@ -540,6 +542,8 @@ paths: $ref: './paths/Spaces.yaml#/~1v3~1spaces~1{guid}~1relationships~1isolation_segment' /v3/spaces/{guid}/routes: $ref: './paths/Spaces.yaml#/~1v3~1spaces~1{guid}~1routes' + /v3/spaces/{guid}/usage_summary: + $ref: './paths/Spaces.yaml#/~1v3~1spaces~1{guid}~1usage_summary' /v3/spaces/{guid}/running_security_groups: $ref: './paths/Spaces.yaml#/~1v3~1spaces~1{guid}~1running_security_groups' /v3/spaces/{guid}/staging_security_groups: diff --git a/apis/cf/latest/paths/Spaces.yaml b/apis/cf/latest/paths/Spaces.yaml index fd34bf1..8864d89 100644 --- a/apis/cf/latest/paths/Spaces.yaml +++ b/apis/cf/latest/paths/Spaces.yaml @@ -483,6 +483,58 @@ $ref: '../components/responses/Forbidden.yaml' '422': $ref: '../components/responses/UnprocessableEntity.yaml' +/v3/spaces/{guid}/usage_summary: + get: + summary: Get usage summary for a space + description: This endpoint retrieves the specified space's memory and app instance + usage summary. + operationId: getUsageSummaryForSpace + tags: + - Spaces + parameters: + - $ref: '../components/parameters/Guid.yaml' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + usage_summary: + type: object + properties: + started_instances: + type: integer + memory_in_mb: + type: integer + routes: + type: integer + service_instances: + type: integer + reserved_ports: + type: integer + domains: + type: integer + per_app_tasks: + type: integer + service_keys: + type: integer + links: + type: object + properties: + self: + $ref: '../components/schemas/Link.yaml' + description: The URL to get this usage summary + space: + $ref: '../components/schemas/Link.yaml' + description: The URL to get the space for this usage summary + '401': + $ref: '../components/responses/Unauthorized.yaml' + '404': + $ref: '../components/responses/NotFound.yaml' + '403': + $ref: '../components/responses/Forbidden.yaml' /v3/spaces/{guid}/running_security_groups: get: summary: List running security groups for a space From 3e6ba4da1769cc2d8107a201562d91029a069df3 Mon Sep 17 00:00:00 2001 From: Peter Levine Date: Tue, 26 May 2026 17:22:06 -0400 Subject: [PATCH 13/14] Add IndexLink schema to handle index link's metadata field (#1051) * Add IndexLink schema to handle index link's metadata field * Reduce Schema Drift and have IndexLink inherit from link Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * V3 api root does not have the meta field * Reference to Link object --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../latest/components/schemas/IndexLink.yaml | 19 +++++++++++++++++++ apis/cf/latest/paths/Root.yaml | 16 ++++++++-------- 2 files changed, 27 insertions(+), 8 deletions(-) create mode 100644 apis/cf/latest/components/schemas/IndexLink.yaml diff --git a/apis/cf/latest/components/schemas/IndexLink.yaml b/apis/cf/latest/components/schemas/IndexLink.yaml new file mode 100644 index 0000000..bb19381 --- /dev/null +++ b/apis/cf/latest/components/schemas/IndexLink.yaml @@ -0,0 +1,19 @@ +allOf: + - $ref: ./Link.yaml + - type: object + properties: + meta: + type: object + description: Contains metadata about the link + properties: + version: + type: string + description: The version of the API + host_key_fingerprint: + type: string + description: The host key fingerprint of the link + oauth_client: + type: string + description: The oauth client for the link +description: | + Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET. Can include a meta object with metadata about the link. diff --git a/apis/cf/latest/paths/Root.yaml b/apis/cf/latest/paths/Root.yaml index 0410b8f..43d47b2 100644 --- a/apis/cf/latest/paths/Root.yaml +++ b/apis/cf/latest/paths/Root.yaml @@ -19,35 +19,35 @@ get: properties: self: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the current endpoint cloud_controller_v2: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Cloud Controller V2 API cloud_controller_v3: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Cloud Controller V3 API network_policy_v1: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Network Policy V1 API uaa: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the UAA API logging: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Logging API log_cache: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Log Cache API log_stream: allOf: - - $ref: '../components/schemas/Link.yaml' + - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Log Stream API '404': $ref: '../components/responses/NotFound.yaml' From 4da09ec304eaeb19511737d24cec41335a438775 Mon Sep 17 00:00:00 2001 From: Peter Levine Date: Fri, 5 Jun 2026 13:53:43 -0400 Subject: [PATCH 14/14] Introduce oasdiff and oasdiff breaking changes workflow on PR to main (#1053) * Introduce oasdiff and oasdiff breaking changes workflow on PR to main * Address security and performance feedback in breaking-changes workflow - Restrict token permissions with `permissions: contents: read` - Prevent token persistence in checkout steps - Use `npm ci --ignore-scripts` to mitigate malicious lifecycle scripts - Implement dependency caching for `npm` to speed up workflow - Add concurrency limits to prevent redundant workflow runs - Add a 10 minute job timeout Co-authored-by: Cursor * Update breaking-changes workflow to use Node 22 and Yarn caching Co-authored-by: Cursor --------- Co-authored-by: Cursor --- .github/workflows/breaking-changes.yaml | 62 +++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 .github/workflows/breaking-changes.yaml diff --git a/.github/workflows/breaking-changes.yaml b/.github/workflows/breaking-changes.yaml new file mode 100644 index 0000000..c36ef41 --- /dev/null +++ b/.github/workflows/breaking-changes.yaml @@ -0,0 +1,62 @@ +name: OpenAPI Breaking Changes +on: + pull_request: + branches: + - main + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + detect-breaking-changes: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + # 1. Checkout Branches + - name: Checkout PR + uses: actions/checkout@v4 + with: + path: pr + persist-credentials: false + + - name: Checkout Base Branch + uses: actions/checkout@v4 + with: + ref: ${{ github.base_ref }} + path: base + persist-credentials: false + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: 'yarn' + cache-dependency-path: | + pr/yarn.lock + base/yarn.lock + + # 2. Build Specs + - name: Build PR Spec + working-directory: pr + run: | + yarn install --frozen-lockfile --ignore-scripts + yarn build + + - name: Build Base Spec + working-directory: base + run: | + yarn install --frozen-lockfile --ignore-scripts + yarn build + + # 3. Compare with oasdiff + - name: Check for Breaking Changes + uses: oasdiff/oasdiff-action/breaking@v0.0.37 + with: + base: 'base/dist/latest/openapi.yaml' + revision: 'pr/dist/latest/openapi.yaml' + fail-on: 'ERR' +