Skip to content

Commit efba23e

Browse files
sethboylesclaude
andcommitted
Bring feature flags, environment variable groups and info to parity with v3
Adds permitted roles to the six authenticated operations, the missing osbapi_version and rate_limits fields on /v3/info, and real schemas for both info endpoints in place of inline stubs. The environment variable group `name` path parameter had no description at all and is now documented and enumerated as running or staging. Language derived from: docs/v3/source/includes/resources/feature_flags/ docs/v3/source/includes/resources/environment_variable_groups/ docs/v3/source/includes/resources/info/ docs/v3/source/includes/api_resources/_feature_flags.erb docs/v3/source/includes/api_resources/_environment_variable_groups.erb docs/v3/source/includes/api_resources/_info.erb The info fields follow app/presenters/v3/info_presenter.rb. The flag list itself is in the Feature Flags tag description. /v3/info states "no authentication required" rather than a roles list, matching the v3 docs, and declares a 429: unauthenticated requests are rate limited (middleware/rate_limiter.rb, middleware/base_rate_limiter.rb). Also fixes, following the implementation: - The hash_based_routing flag is accepted by the name parameter; it exists in FeatureFlag::DEFAULT_FLAGS but not in the v3 flag table. - EnvironmentVariableGroup.name was nullable; the presenter always returns running or staging. - Response code sets trimmed to what these endpoints can actually return (/v3/info takes no auth, parameters or body, yet declared 400/403/404/ 409/422/502). To keep code generated from the spec stable (GraphQL Mesh, for example, derives type, field and argument names from its structure), this also: - Query parameters keep their existing order, and `order_by` stays a plain string with the valid values in its description. Generators key argument handling off both. - Response values that were previously undeclared stay listed in the description rather than becoming a new `enum`. ai-assisted=yes Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent bf7868b commit efba23e

8 files changed

Lines changed: 191 additions & 134 deletions

File tree

‎docs/openapi/apis/cf/latest/components/schemas/EnvironmentVariableGroup.yaml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,18 @@ properties:
33
updated_at:
44
type: string
55
format: date-time
6-
description: The time the environment variable group was last updated
6+
description: The time of last update
77
name:
8-
type: [string, "null"]
9-
description: The name of the group; can only be "running" or "staging"
8+
type: string
9+
description: The name of the group; can only be `running` or `staging`
1010
var:
1111
type: object
1212
additionalProperties:
13-
type: [string, "null"]
13+
type: string
1414
description: Environment variables to inject; keys and values must be strings
1515
links:
1616
type: object
17+
description: Links to related resources
1718
properties:
1819
self:
1920
$ref: './Link.yaml'

‎docs/openapi/apis/cf/latest/components/schemas/FeatureFlag.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,13 @@ properties:
99
updated_at:
1010
type: [string, "null"]
1111
format: date-time
12-
description: The time the feature flag was last updated; this will be blank for feature flags that have not been configured
12+
description: The time with zone when the object was last updated; this will be blank for feature flags that have not been configured
1313
custom_error_message:
1414
type: [string, "null"]
1515
description: The error string returned by the API when a client performs an action disabled by the feature flag
1616
links:
1717
type: object
18+
description: Links to related resources
1819
properties:
1920
self:
2021
$ref: './Link.yaml'
Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
type: object
22
properties:
33
pagination:
4-
$ref: './Pagination.yaml'
4+
allOf:
5+
- $ref: './Pagination.yaml'
6+
- description: Pagination information for the list of feature flags
57
resources:
68
type: array
9+
description: A list of feature flags
710
items:
811
$ref: './FeatureFlag.yaml'
12+
description: >
13+
A paginated list of feature flags.
Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
type: object
2+
properties:
3+
build:
4+
type: string
5+
description: The Cloud Controller build number, as configured by the platform operator; blank when it is not configured
6+
cli_version:
7+
type: object
8+
description: Minimum and recommended versions of the Cloud Foundry CLI for use with this API
9+
properties:
10+
minimum:
11+
type: string
12+
description: Minimum version of the CF CLI to work with the API; blank when it is not configured
13+
recommended:
14+
type: string
15+
description: Minimum recommended version of the CF CLI; blank when it is not configured
16+
custom:
17+
type: object
18+
additionalProperties: true
19+
description: Custom attribute keys and values configured by the platform operator; empty when none are configured
20+
description:
21+
type: string
22+
description: A description of the platform, as configured by the platform operator; blank when it is not configured
23+
name:
24+
type: string
25+
description: The name of the platform, as configured by the platform operator; blank when it is not configured
26+
version:
27+
type: integer
28+
description: The version of the platform, as configured by the platform operator; `0` when it is not configured
29+
osbapi_version:
30+
type: string
31+
description: The version of the Open Service Broker API supported by this platform; blank when it cannot be determined
32+
rate_limits:
33+
type: object
34+
description: The request rate limits applied to UAA-authenticated endpoints
35+
properties:
36+
enabled:
37+
type: boolean
38+
description: Whether rate limiting is enabled for UAA-authenticated endpoints per user or client
39+
general_limit:
40+
type: integer
41+
description: The number of requests that a user or client is allowed to make over the reset interval for all endpoints that do not have a custom limit
42+
reset_interval_in_minutes:
43+
type: integer
44+
description: The interval in minutes after which a user's available API requests will be reset
45+
links:
46+
type: object
47+
description: Links to related resources
48+
properties:
49+
self:
50+
allOf:
51+
- $ref: './Link.yaml'
52+
- description: Link to the current endpoint
53+
support:
54+
allOf:
55+
- $ref: './Link.yaml'
56+
- description: Link to the support address for the platform; blank when it is not configured
57+
description: |-
58+
Descriptive information about the Cloud Controller and the platform it is running on.
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
type: object
2+
properties:
3+
usage_summary:
4+
type: object
5+
description: A high-level summary of usage across the entire Cloud Foundry installation
6+
properties:
7+
started_instances:
8+
type: integer
9+
description: Total number of process instances in the `STARTED` state
10+
memory_in_mb:
11+
type: integer
12+
description: Sum of memory usage of all tasks in the `RUNNING` state and all process instances in the `STARTED` state
13+
routes:
14+
type: integer
15+
description: Total number of routes
16+
service_instances:
17+
type: integer
18+
description: Total number of managed service instances
19+
reserved_ports:
20+
type: integer
21+
description: Total number of reserved ports
22+
domains:
23+
type: integer
24+
description: Total number of private domains
25+
per_app_tasks:
26+
type: integer
27+
description: Total number of running tasks
28+
service_keys:
29+
type: integer
30+
description: Total number of service keys
31+
links:
32+
type: object
33+
description: Links to related resources
34+
properties:
35+
self:
36+
allOf:
37+
- $ref: './Link.yaml'
38+
- description: Link to the current endpoint
39+
description: |-
40+
A high-level summary of usage across the entire Cloud Foundry installation.

‎docs/openapi/apis/cf/latest/paths/EnvironmentVariableGroups.yaml‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
/v3/environment_variable_groups/{name}:
22
get:
33
summary: Get an environment variable group
4-
description: Retrieve an environment variable group.
4+
description: |-
5+
Retrieve an environment variable group.
6+
7+
**Permitted roles:** All Roles
58
operationId: getEnvironmentVariableGroup
69
tags:
710
- Environment Variable Groups
@@ -14,6 +17,7 @@
1417
enum:
1518
- running
1619
- staging
20+
description: The name of the group; can only be `running` or `staging`
1721
responses:
1822
'200':
1923
description: OK
@@ -32,30 +36,27 @@
3236
links:
3337
self:
3438
href: https://api.example.org/v3/environment_variable_groups/running
35-
'400':
36-
$ref: ../components/responses/BadRequest.yaml
3739
'401':
3840
$ref: ../components/responses/Unauthorized.yaml
3941
'403':
4042
$ref: ../components/responses/Forbidden.yaml
4143
'404':
4244
$ref: ../components/responses/NotFound.yaml
43-
'409':
44-
$ref: ../components/responses/Conflict.yaml
45-
'422':
46-
$ref: ../components/responses/UnprocessableEntity.yaml
4745
'500':
4846
$ref: ../components/responses/500.yaml
49-
'502':
50-
$ref: ../components/responses/BadGateway.yaml
5147
'503':
5248
$ref: ../components/responses/ServiceUnavailable.yaml
5349
patch:
5450
summary: Update environment variable group
5551
description: |-
56-
Update the environment variable group. The variables given in the request will be merged with the existing environment variable group. Any requested variables with a value of `null` will be removed from the group. Environment variable names may not start with VCAP_. PORT is not a valid environment variable.
52+
Update the environment variable group.
53+
The variables given in the request will be merged with the existing environment variable group.
54+
Any requested variables with a value of `null` will be removed from the group.
55+
Environment variable names may not start with VCAP_. PORT is not a valid environment variable.
56+
57+
> **Note:** Variables updated in the **running** environment variable group will not take effect until apps are restarted.
5758
58-
Variables updated in the **running** environment variable group will not take effect until apps are restarted.
59+
**Permitted roles:** Admin
5960
operationId: updateEnvironmentVariableGroup
6061
tags:
6162
- Environment Variable Groups
@@ -68,6 +69,7 @@
6869
enum:
6970
- running
7071
- staging
72+
description: The name of the group; can only be `running` or `staging`
7173
requestBody:
7274
description: The environment variables to update
7375
required: true
@@ -79,8 +81,15 @@
7981
var:
8082
type: object
8183
additionalProperties:
82-
type: string
83-
description: Environment variables to inject; keys and values must be strings
84+
type: [string, "null"]
85+
description: Environment variables to inject; keys and values must be strings. A value of `null` removes the variable from the group
86+
examples:
87+
default:
88+
summary: default
89+
value:
90+
var:
91+
DEBUG: 'false'
92+
USER: null
8493
responses:
8594
'200':
8695
description: OK
@@ -92,12 +101,14 @@
92101
default:
93102
summary: default
94103
value:
104+
updated_at: '2016-05-04T17:00:41Z'
105+
name: running
95106
var:
96107
RAILS_ENV: production
97108
DEBUG: 'false'
98109
links:
99110
self:
100-
href: https://api.example.org/v3/environment_variable_groups/[name]
111+
href: https://api.example.org/v3/environment_variable_groups/running
101112
'400':
102113
$ref: ../components/responses/BadRequest.yaml
103114
'401':
@@ -106,8 +117,6 @@
106117
$ref: ../components/responses/Forbidden.yaml
107118
'404':
108119
$ref: ../components/responses/NotFound.yaml
109-
'409':
110-
$ref: ../components/responses/Conflict.yaml
111120
'422':
112121
$ref: ../components/responses/UnprocessableEntity.yaml
113122
'500':

‎docs/openapi/apis/cf/latest/paths/FeatureFlags.yaml‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
11
/v3/feature_flags:
22
get:
33
summary: List feature flags
4-
description: Retrieve all feature_flags.
4+
description: |-
5+
Retrieve all feature_flags.
6+
7+
**Permitted roles:** All Roles
58
operationId: listFeatureFlags
69
tags:
710
- Feature Flags
811
parameters:
912
- $ref: ../components/parameters/Page.yaml
1013
- $ref: ../components/parameters/PerPage.yaml
11-
- $ref: ../components/parameters/OrderBy.yaml
12-
- name: updated_ats
14+
- name: order_by
1315
in: query
1416
required: false
1517
schema:
1618
type: string
17-
description: |
18-
Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed.
19+
description: Value to sort by. Defaults to `name` ascending; prepend with `-` to sort descending. Valid value is `name`
20+
- $ref: ../components/parameters/UpdatedAts.yaml
1921
responses:
2022
'200':
2123
description: OK
@@ -58,20 +60,17 @@
5860
$ref: ../components/responses/Unauthorized.yaml
5961
'403':
6062
$ref: ../components/responses/Forbidden.yaml
61-
'409':
62-
$ref: ../components/responses/Conflict.yaml
63-
'422':
64-
$ref: ../components/responses/UnprocessableEntity.yaml
6563
'500':
6664
$ref: ../components/responses/500.yaml
67-
'502':
68-
$ref: ../components/responses/BadGateway.yaml
6965
'503':
7066
$ref: ../components/responses/ServiceUnavailable.yaml
7167
/v3/feature_flags/{name}:
7268
get:
7369
summary: Get a feature flag
74-
description: Get a feature flag.
70+
description: |-
71+
Get a feature flag.
72+
73+
**Permitted roles:** All Roles
7574
operationId: getFeatureFlag
7675
tags:
7776
- Feature Flags
@@ -87,6 +86,7 @@
8786
- diego_docker
8887
- diego_cnb
8988
- env_var_visibility
89+
- hash_based_routing
9090
- hide_marketplace_from_unauthenticated_users
9191
- private_domain_creation
9292
- resource_matching
@@ -100,7 +100,7 @@
100100
- task_creation
101101
- unset_roles_by_username
102102
- user_org_creation
103-
description: The name of the feature flag
103+
description: The name of the feature flag; must be one of the names in the [list of feature flags](#list-of-feature-flags)
104104
responses:
105105
'200':
106106
description: Successfully retrieved feature flag
@@ -127,7 +127,10 @@
127127
$ref: ../components/responses/NotFound.yaml
128128
patch:
129129
summary: Update a feature flag
130-
description: Update a feature flag.
130+
description: |-
131+
Update a feature flag.
132+
133+
**Permitted roles:** Admin
131134
operationId: updateFeatureFlag
132135
tags:
133136
- Feature Flags
@@ -143,6 +146,7 @@
143146
- diego_docker
144147
- diego_cnb
145148
- env_var_visibility
149+
- hash_based_routing
146150
- hide_marketplace_from_unauthenticated_users
147151
- private_domain_creation
148152
- resource_matching
@@ -156,7 +160,7 @@
156160
- task_creation
157161
- unset_roles_by_username
158162
- user_org_creation
159-
description: The name of the feature flag
163+
description: The name of the feature flag; must be one of the names in the [list of feature flags](#list-of-feature-flags)
160164
requestBody:
161165
description: Feature flag object that needs to be updated
162166
required: true
@@ -169,7 +173,7 @@
169173
type: boolean
170174
description: Whether the feature flag is enabled
171175
custom_error_message:
172-
type: string
176+
type: [string, "null"]
173177
description: The error string returned by the API when a client performs an action disabled by the feature flag
174178
examples:
175179
default:
@@ -203,8 +207,6 @@
203207
$ref: ../components/responses/Forbidden.yaml
204208
'404':
205209
$ref: ../components/responses/NotFound.yaml
206-
'409':
207-
$ref: ../components/responses/Conflict.yaml
208210
'422':
209211
$ref: ../components/responses/UnprocessableEntity.yaml
210212
'500':

0 commit comments

Comments
 (0)