From 009f5ca46c224e4edad847d44f97a42489099f2b Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Fri, 4 Sep 2026 20:19:20 -0600 Subject: [PATCH 1/2] Add the Route Policies resource to the OpenAPI spec Route policies are documented in the v3 reference docs and implemented in config/routes.rb, but were entirely absent from the spec. Adds all five endpoints, the route policy object and list schemas, the create and update request bodies, and the registry entries. Language derived from: docs/v3/source/includes/resources/route_policies/ docs/v3/source/includes/api_resources/_route_policies.erb (examples) Verified against config/routes.rb and app/controllers/v3/route_policies_controller.rb; the include parameter's valid values come from RoutePolicyShowMessage/RoutePoliciesListMessage. The v3 "Use cases" section is condensed into bullets on the create operation rather than reproduced as curl blocks. ai-assisted=yes Co-Authored-By: Claude Sonnet 5 --- .../RoutePolicyCreateRequestBody.yaml | 55 +++ .../RoutePolicyUpdateRequestBody.yaml | 19 + .../components/schemas/RoutePolicy.yaml | 65 +++ .../components/schemas/RoutePolicyList.yaml | 13 + docs/openapi/apis/cf/latest/openapi.yaml | 6 + .../apis/cf/latest/paths/RoutePolicies.yaml | 426 ++++++++++++++++++ 6 files changed, 584 insertions(+) create mode 100644 docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyCreateRequestBody.yaml create mode 100644 docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyUpdateRequestBody.yaml create mode 100644 docs/openapi/apis/cf/latest/components/schemas/RoutePolicy.yaml create mode 100644 docs/openapi/apis/cf/latest/components/schemas/RoutePolicyList.yaml create mode 100644 docs/openapi/apis/cf/latest/paths/RoutePolicies.yaml diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyCreateRequestBody.yaml new file mode 100644 index 00000000000..483af2c90db --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyCreateRequestBody.yaml @@ -0,0 +1,55 @@ +description: Route policy to create +required: true +content: + application/json: + schema: + type: object + properties: + source: + type: string + description: The policy selector. Must be `cf:app:`, `cf:space:`, `cf:org:`, or `cf:any` + relationships: + type: object + properties: + route: + $ref: ../schemas/RelationshipToOne.yaml + description: The route this policy applies to + required: + - route + description: A relationship to the route this policy applies to + metadata: + $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the route policy + required: + - source + - relationships + examples: + default: + summary: Allow specific app + value: + source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08 + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + metadata: + labels: + team: frontend + annotations: + description: Allow frontend app to call backend API + space: + summary: Allow all apps in a space + value: + source: cf:space:3fa85f64-5717-4562-b3fc-2c963f66afa6 + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + any: + summary: Allow any caller + value: + source: cf:any + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyUpdateRequestBody.yaml new file mode 100644 index 00000000000..d80591648ea --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyUpdateRequestBody.yaml @@ -0,0 +1,19 @@ +description: Route policy metadata to update +required: true +content: + application/json: + schema: + type: object + properties: + metadata: + $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the route policy + examples: + default: + summary: default + value: + metadata: + labels: + team: backend + annotations: + note: Updated contact info diff --git a/docs/openapi/apis/cf/latest/components/schemas/RoutePolicy.yaml b/docs/openapi/apis/cf/latest/components/schemas/RoutePolicy.yaml new file mode 100644 index 00000000000..995d9992f31 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/RoutePolicy.yaml @@ -0,0 +1,65 @@ +type: object +allOf: + - $ref: './BaseSchema.yaml' + - properties: + source: + type: string + description: |- + The policy selector specifying who can access the route. Must be one of: + - `cf:app:` (specific app) + - `cf:space:` (all apps in a space) + - `cf:org:` (all apps in an organization) + - `cf:any` (any caller - cannot be combined with other sources) + metadata: + $ref: './Metadata.yaml' + description: Labels and annotations applied to the route policy + relationships: + type: object + properties: + route: + $ref: './RelationshipToOne.yaml' + description: The route this policy applies to + app: + $ref: './RelationshipToOne.yaml' + description: Read-only. Always present; `data` is `null` unless the source is `cf:app:` + space: + $ref: './RelationshipToOne.yaml' + description: Read-only. Always present; `data` is `null` unless the source is `cf:space:` + organization: + $ref: './RelationshipToOne.yaml' + description: Read-only. Always present; `data` is `null` unless the source is `cf:org:` + description: Relationships to the route this policy applies to and to the app, space, or organization referenced by the source + links: + type: object + properties: + self: + $ref: './Link.yaml' + description: The URL to get this route policy + route: + $ref: './Link.yaml' + description: The URL to get the route this policy applies to + app: + $ref: './Link.yaml' + description: The URL to get the app referenced by the source; only present when the source is `cf:app:` + space: + $ref: './Link.yaml' + description: The URL to get the space referenced by the source; only present when the source is `cf:space:` + organization: + $ref: './Link.yaml' + description: The URL to get the organization referenced by the source; only present when the source is `cf:org:` + description: Links to related resources. Always includes `self` and `route`; includes `app`, `space`, or `organization` when the source references that resource + included: + $ref: './IncludedResources.yaml' + description: Additional related resources included in the response when using the include parameter +description: |- + Route policies control which Cloud Foundry apps, spaces, or organizations can access routes on identity-aware domains. When a domain has `enforce_route_policies` enabled, GoRouter automatically enforces these access controls using mutual TLS (mTLS) to verify the identity of the calling application. + + Route policies are defined using a `source` selector that specifies who can access the route: + - `cf:app:` - Allow a specific app + - `cf:space:` - Allow all apps in a space + - `cf:org:` - Allow all apps in an organization + - `cf:any` - Allow any caller (cannot be combined with other sources on the same route) + + > **Note:** Route policies can only be created for routes on domains where `enforce_route_policies` is `true` and the domain is not internal (internal routes use container-to-container networking and bypass GoRouter). + + **This feature is experimental and is subject to change.** diff --git a/docs/openapi/apis/cf/latest/components/schemas/RoutePolicyList.yaml b/docs/openapi/apis/cf/latest/components/schemas/RoutePolicyList.yaml new file mode 100644 index 00000000000..45cf43f3a83 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/RoutePolicyList.yaml @@ -0,0 +1,13 @@ +type: object +properties: + pagination: + $ref: './Pagination.yaml' + resources: + type: array + items: + $ref: './RoutePolicy.yaml' + description: List of route policies + included: + $ref: './IncludedResources.yaml' + description: Additional related resources included in the response when using the include parameter +description: A list of route policies diff --git a/docs/openapi/apis/cf/latest/openapi.yaml b/docs/openapi/apis/cf/latest/openapi.yaml index dcd3c9cbcb5..cd4fb236508 100644 --- a/docs/openapi/apis/cf/latest/openapi.yaml +++ b/docs/openapi/apis/cf/latest/openapi.yaml @@ -60,6 +60,8 @@ tags: description: "Root API endpoints that provide entry points and API information." - name: Routes description: "Routes are used to map a URL to an app." + - name: Route Policies + description: "Route policies control which callers can access routes on identity-aware domains." - name: Security Groups description: "Security groups are used to control access to apps." - name: Service Brokers @@ -464,6 +466,10 @@ paths: $ref: './paths/Roles.yaml#/~1v3~1roles' /v3/roles/{guid}: $ref: './paths/Roles.yaml#/~1v3~1roles~1{guid}' + /v3/route_policies: + $ref: './paths/RoutePolicies.yaml#/~1v3~1route_policies' + /v3/route_policies/{guid}: + $ref: './paths/RoutePolicies.yaml#/~1v3~1route_policies~1{guid}' /v3/routes: $ref: './paths/Routes.yaml#/~1v3~1routes' /v3/routes/{guid}/destinations: diff --git a/docs/openapi/apis/cf/latest/paths/RoutePolicies.yaml b/docs/openapi/apis/cf/latest/paths/RoutePolicies.yaml new file mode 100644 index 00000000000..f9ca0429f86 --- /dev/null +++ b/docs/openapi/apis/cf/latest/paths/RoutePolicies.yaml @@ -0,0 +1,426 @@ +/v3/route_policies: + get: + summary: List route policies + description: |- + Retrieve all route policies the user has access to. + + **Filtering examples** + + - **Filter by route**: `GET /v3/route_policies?route_guids=89b32bd6-688f-4424-b94f-2e2c86495a5f` + - **Filter by space**: `GET /v3/route_policies?space_guids=3fa85f64-5717-4562-b3fc-2c963f66afa6` + - **Filter by source type**: `GET /v3/route_policies?sources=cf:any` + - **Find policies referencing a specific app**: `GET /v3/route_policies?source_guids=d76446a1-f429-4444-8797-be2f78b75b08` + - **Include source resources**: `GET /v3/route_policies?include=source` (batch-loads the app, space, or org referenced in each policy's source) + - **Include route and source**: `GET /v3/route_policies?include=route,source` + + **This feature is experimental and is subject to change.** + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Org Auditor, Org Billing Manager *(will receive an empty list)*, Space Auditor, Space Developer, Space Manager, Space Supporter + operationId: listRoutePolicies + tags: + - Route Policies + parameters: + - name: guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of route policy guids to filter by + - name: route_guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of route guids to filter by + - name: space_guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of space guids to filter by (filters by the route's space) + - name: sources + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of exact source strings to filter by (e.g., `cf:any`, `cf:app:guid`) + - name: source_guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of GUIDs to filter by; matches the GUID portion of the source (e.g. the app, space, or org GUID) + - $ref: ../components/parameters/Page.yaml + - $ref: ../components/parameters/PerPage.yaml + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + - updated_at + - -updated_at + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at` + - $ref: ../components/parameters/LabelSelector.yaml + - name: include + in: query + required: false + schema: + type: array + items: + type: string + enum: + - route + - source + description: Optionally include related resources in the response; valid values are `route` and `source` (source includes the app, space, or organization based on the source type) + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/RoutePolicyList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/route_policies?page=1&per_page=2 + last: + href: https://api.example.org/v3/route_policies?page=2&per_page=2 + next: + href: https://api.example.org/v3/route_policies?page=2&per_page=2 + previous: null + resources: + - guid: a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + created_at: '2026-04-21T10:15:30Z' + updated_at: '2026-04-21T10:15:30Z' + source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08 + metadata: + labels: {} + annotations: {} + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + data: + guid: d76446a1-f429-4444-8797-be2f78b75b08 + space: + data: null + organization: + data: null + links: + self: + href: https://api.example.org/v3/route_policies/a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + route: + href: https://api.example.org/v3/routes/89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + href: https://api.example.org/v3/apps/d76446a1-f429-4444-8797-be2f78b75b08 + - guid: f2b5d8c3-92a1-4e3f-b847-9c8f1d2e3a4b + created_at: '2026-04-21T11:20:45Z' + updated_at: '2026-04-21T11:20:45Z' + source: cf:space:3fa85f64-5717-4562-b3fc-2c963f66afa6 + metadata: + labels: {} + annotations: {} + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + data: null + space: + data: + guid: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + organization: + data: null + links: + self: + href: https://api.example.org/v3/route_policies/f2b5d8c3-92a1-4e3f-b847-9c8f1d2e3a4b + route: + href: https://api.example.org/v3/routes/89b32bd6-688f-4424-b94f-2e2c86495a5f + space: + href: https://api.example.org/v3/spaces/3fa85f64-5717-4562-b3fc-2c963f66afa6 + '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 + '503': + $ref: ../components/responses/ServiceUnavailable.yaml + post: + summary: Create a route policy + description: |- + Create a route policy granting the given source access to a route on an identity-aware domain. + + **Validation rules** + + - The route's domain must have `enforce_route_policies` set to `true` + - The route's domain must not be internal (internal routes bypass GoRouter) + - The `source` must be unique per route (duplicate sources are rejected) + - If the route already has a `cf:any` policy, no other sources can be added + - If adding `cf:any`, the route must not have any existing policies + - The source GUID is not checked for existence at creation time; stale references are tolerated, and sources referencing resources the caller cannot see are accepted but do not appear under `?include=source` + - The `app`, `space`, and `organization` relationships are derived from `source` and cannot be set directly + + **Common use cases** + + - Allow a frontend app to call a backend API: create a policy with `source` of `cf:app:` on the backend route + - Allow all apps in a space to access a shared service: create a policy with `source` of `cf:space:` on the shared service route + - Open a route to any caller (public API): create a policy with `source` of `cf:any` + + **This feature is experimental and is subject to change.** + + **Permitted roles:** Admin, Space Developer *(can create policies for routes in spaces they can write to)* + operationId: createRoutePolicy + tags: + - Route Policies + requestBody: + $ref: ../components/requestBodies/RoutePolicyCreateRequestBody.yaml + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: ../components/schemas/RoutePolicy.yaml + examples: + default: + summary: default + value: + guid: a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + created_at: '2026-04-21T10:15:30Z' + updated_at: '2026-04-21T10:15:30Z' + source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08 + metadata: + labels: + team: frontend + annotations: + description: Allow frontend app to call backend API + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + data: + guid: d76446a1-f429-4444-8797-be2f78b75b08 + space: + data: null + organization: + data: null + links: + self: + href: https://api.example.org/v3/route_policies/a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + route: + href: https://api.example.org/v3/routes/89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + href: https://api.example.org/v3/apps/d76446a1-f429-4444-8797-be2f78b75b08 + '400': + $ref: ../components/responses/BadRequest.yaml + '401': + $ref: ../components/responses/Unauthorized.yaml + '403': + $ref: ../components/responses/Forbidden.yaml + '404': + $ref: ../components/responses/NotFound.yaml + '422': + $ref: ../components/responses/UnprocessableEntity.yaml + '500': + $ref: ../components/responses/500.yaml + '503': + $ref: ../components/responses/ServiceUnavailable.yaml +/v3/route_policies/{guid}: + get: + summary: Get a route policy + description: |- + Retrieve a single route policy. + + **This feature is experimental and is subject to change.** + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Org Auditor, Org Billing Manager *(will not be able to see any route policies)*, Space Auditor, Space Developer, Space Manager, Space Supporter + operationId: getRoutePolicy + tags: + - Route Policies + parameters: + - $ref: ../components/parameters/Guid.yaml + - name: include + in: query + required: false + schema: + type: array + items: + type: string + enum: + - route + - source + description: Optionally include a list of unique related resources in the response; valid values are `route` and `source` (source includes the app, space, or organization referenced by the source field) + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/RoutePolicy.yaml + examples: + default: + summary: default + value: + guid: a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + created_at: '2026-04-21T10:15:30Z' + updated_at: '2026-04-21T10:15:30Z' + source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08 + metadata: + labels: {} + annotations: {} + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + data: + guid: d76446a1-f429-4444-8797-be2f78b75b08 + space: + data: null + organization: + data: null + links: + self: + href: https://api.example.org/v3/route_policies/a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + route: + href: https://api.example.org/v3/routes/89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + href: https://api.example.org/v3/apps/d76446a1-f429-4444-8797-be2f78b75b08 + '400': + $ref: ../components/responses/BadRequest.yaml + '401': + $ref: ../components/responses/Unauthorized.yaml + '403': + $ref: ../components/responses/Forbidden.yaml + '404': + $ref: ../components/responses/NotFound.yaml + '422': + $ref: ../components/responses/UnprocessableEntity.yaml + '500': + $ref: ../components/responses/500.yaml + '503': + $ref: ../components/responses/ServiceUnavailable.yaml + patch: + summary: Update a route policy + description: |- + Update the metadata of a route policy. + + > **Note:** This endpoint only supports updating metadata (labels and annotations). The `source` and route relationship are immutable after creation. To change the source, delete the policy and create a new one. + + **This feature is experimental and is subject to change.** + + **Permitted roles:** Admin, Space Developer *(can update policies for routes in spaces they can write to)* + operationId: updateRoutePolicy + tags: + - Route Policies + parameters: + - $ref: ../components/parameters/Guid.yaml + requestBody: + $ref: ../components/requestBodies/RoutePolicyUpdateRequestBody.yaml + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ../components/schemas/RoutePolicy.yaml + examples: + default: + summary: default + value: + guid: a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + created_at: '2026-04-21T10:15:30Z' + updated_at: '2026-04-21T10:15:30Z' + source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08 + metadata: + labels: + team: backend + annotations: + note: Updated contact info + relationships: + route: + data: + guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + data: + guid: d76446a1-f429-4444-8797-be2f78b75b08 + space: + data: null + organization: + data: null + links: + self: + href: https://api.example.org/v3/route_policies/a4ad8bc1-67a6-4ffa-95b7-f8cf04ad7d4f + route: + href: https://api.example.org/v3/routes/89b32bd6-688f-4424-b94f-2e2c86495a5f + app: + href: https://api.example.org/v3/apps/d76446a1-f429-4444-8797-be2f78b75b08 + '400': + $ref: ../components/responses/BadRequest.yaml + '401': + $ref: ../components/responses/Unauthorized.yaml + '403': + $ref: ../components/responses/Forbidden.yaml + '404': + $ref: ../components/responses/NotFound.yaml + '422': + $ref: ../components/responses/UnprocessableEntity.yaml + '500': + $ref: ../components/responses/500.yaml + '503': + $ref: ../components/responses/ServiceUnavailable.yaml + delete: + summary: Delete a route policy + description: |- + Deleting a route policy removes the access control for that specific source. If this was the only policy on the route, the route will become inaccessible (no callers will be allowed) until new policies are added or a `cf:any` policy is created. + + **This feature is experimental and is subject to change.** + + **Permitted roles:** Admin, Space Developer *(can delete policies for routes in spaces they can write to)* + operationId: deleteRoutePolicy + tags: + - Route Policies + parameters: + - $ref: ../components/parameters/Guid.yaml + responses: + '204': + description: No Content + '401': + $ref: ../components/responses/Unauthorized.yaml + '403': + $ref: ../components/responses/Forbidden.yaml + '404': + $ref: ../components/responses/NotFound.yaml + '422': + $ref: ../components/responses/UnprocessableEntity.yaml + '500': + $ref: ../components/responses/500.yaml + '503': + $ref: ../components/responses/ServiceUnavailable.yaml From f3487361f56fef9885206060b983fe4a2c4a4bae Mon Sep 17 00:00:00 2001 From: Seth Boyles Date: Fri, 4 Sep 2026 20:20:58 -0600 Subject: [PATCH 2/2] Bring domains and isolation segments to parity with the v3 reference docs Adds permitted roles to all 15 operations with their v3 qualifiers, the enforce_route_policies and route_policies_scope domain fields, explicit organization and shared_organizations relationships in place of an opaque Relationships ref, and the missing filters on the org-scoped domain list and the isolation segment organizations list. Language derived from: docs/v3/source/includes/resources/domains/ docs/v3/source/includes/resources/isolation_segments/ docs/v3/source/includes/api_resources/_domains.erb docs/v3/source/includes/api_resources/_isolation_segments.erb Also fixes: - The share-a-domain response schema had `items` mis-indented as a sibling of `data`, so the schema was malformed, and its request description was copy-pasted from isolation segments. - The isolation segment PATCH example contained literal ERB (`name: <%= name %>`). - page/per_page removed from the two relationship endpoints, which accept no query parameters and return an unpaginated relationship. - created_ats/updated_ats added to GET /v3/organizations/{guid}/domains: undocumented in v3, but the controller reuses DomainsListMessage. - PATCH /v3/domains/{guid} now references the orphaned DomainUpdateRequestBody. ai-assisted=yes Co-Authored-By: Claude Sonnet 5 --- .../DomainCreateRequestBody.yaml | 32 +- .../DomainUpdateRequestBody.yaml | 10 + .../requestBodies/IsolationSegmentCreate.yaml | 4 +- .../cf/latest/components/schemas/Domain.yaml | 41 ++- .../latest/components/schemas/DomainList.yaml | 3 + .../components/schemas/IsolationSegment.yaml | 8 +- .../schemas/IsolationSegmentList.yaml | 3 + .../openapi/apis/cf/latest/paths/Domains.yaml | 300 ++++++++++++++---- .../cf/latest/paths/IsolationSegments.yaml | 153 ++++++--- 9 files changed, 431 insertions(+), 123 deletions(-) diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml index 12b0e53d79f..22d5cac8473 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml @@ -9,31 +9,53 @@ content: properties: name: type: string - description: Name of the domain + description: Name of the domain; must be unique (case-insensitive) internal: type: boolean - description: Whether the domain is used for internal (container-to-container) traffic + default: false + description: Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic router_group: type: object properties: guid: type: string format: uuid - description: 'The desired router group guid. _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_' + description: The desired router group guid + description: 'The desired router group. _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_' + enforce_route_policies: + type: boolean + default: false + description: When `true`, GoRouter enforces route policies for routes on this domain using mutual TLS (mTLS). Set at creation only; cannot be changed on update. Cannot be used with internal domains + route_policies_scope: + type: string + enum: + - any + - org + - space + description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update' relationships: type: object properties: organization: $ref: ../schemas/RelationshipToOne.yaml - description: A relationship to the organization the domain will be scoped to; _note cannot be used when `internal` is set to `true` or domain is associated with a router group_ + description: 'A relationship to the organization the domain will be scoped to; _note: cannot be used when `internal` is set to `true` or domain is associated with a router group_' shared_organizations: $ref: ../schemas/RelationshipToMany.yaml - description: A relationship to organizations the domain will be shared with _Note cannot be used without an organization relationship_ + description: 'A relationship to organizations the domain will be shared with. _Note: cannot be used without an organization relationship_' + description: Relationships to the organization the domain will be scoped to and the organizations the domain will be shared with metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the domain examples: default: summary: default value: name: example.com internal: false + identityAwareDomain: + summary: Identity-aware domain + value: + name: apps.identity + internal: false + enforce_route_policies: true + route_policies_scope: org diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml index 006b25879e7..353c65b6949 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml @@ -7,4 +7,14 @@ content: properties: metadata: $ref: '../schemas/Metadata.yaml' + description: Labels and annotations applied to the domain description: Request schema for updating a domain + examples: + default: + summary: default + value: + metadata: + labels: + key: value + annotations: + note: detailed information diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml index 53466cecdf6..f6b5cc66726 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml @@ -1,4 +1,5 @@ description: Isolation segment to create +required: true content: application/json: schema: @@ -6,9 +7,10 @@ content: properties: name: type: string - description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness + description: Name of the isolation segment; must be unique (case-insensitive) metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the isolation segment required: - name examples: diff --git a/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml b/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml index 520314e54e4..0af37f0dea8 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml @@ -9,14 +9,15 @@ allOf: type: boolean description: Whether the domain is used for internal (container-to-container) traffic router_group: - type: + type: - object - 'null' properties: guid: type: string format: uuid - description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic + description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic + description: The router group the domain routes `tcp` traffic through; if set, the domain will only be available for `tcp` traffic supported_protocols: type: array items: @@ -25,10 +26,29 @@ allOf: - http - tcp description: Available protocols for routes using the domain, currently `http` and `tcp` + enforce_route_policies: + type: boolean + description: When `true`, GoRouter enforces route policies for routes on this domain. This field only appears in the response when set to `true`. Set at creation only; cannot be changed on update + route_policies_scope: + type: string + enum: + - any + - org + - space + description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. This field only appears when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update' relationships: - $ref: './Relationships.yaml' + type: object + properties: + organization: + $ref: './RelationshipToOne.yaml' + description: The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available + shared_organizations: + $ref: './RelationshipToMany.yaml' + description: Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to + description: Relationships to the organization the domain is scoped to and the organizations the domain is shared with metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the domain links: type: object properties: @@ -37,15 +57,18 @@ allOf: description: The URL to get this domain organization: $ref: './Link.yaml' - description: The URL to get the organization for this domain + description: The URL to get the organization this domain is scoped to; only present for organization-scoped domains route_reservations: $ref: './Link.yaml' - description: The URL to get the route reservations for this domain + description: The URL to check which routes are reserved for this domain shared_organizations: $ref: './Link.yaml' - description: The URL to get the shared organizations for this domain + description: The URL to get the organizations this domain is shared with; only present for organization-scoped domains router_group: $ref: './Link.yaml' - description: The URL to get the router group for this domain -description: | - A domain is a fully qualified domain name that is used for application routes. A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access. + description: The URL to get the router group for this domain; only present for domains associated with a router group + description: Links to related resources +description: |- + Domains represent a [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) that is used for application routes. + + A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access. diff --git a/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml b/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml index 4cebea5d499..8c477f390aa 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of domains resources: type: array items: $ref: './Domain.yaml' + description: List of domains +description: A paginated list of domains diff --git a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml index 4007eaa6233..cf243ef0a7d 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml @@ -4,9 +4,10 @@ allOf: - properties: name: type: string - description: The name of the isolation segment + description: Name of the isolation segment metadata: $ref: './Metadata.yaml' + description: Labels and annotations on the isolation segment links: type: object properties: @@ -15,5 +16,6 @@ allOf: description: The URL to get this isolation segment organizations: $ref: './Link.yaml' - description: The URL to get the organizations for this isolation segment -description: An isolation segment provides a dedicated pool of compute resources for an organization or space. + description: The URL to get the organizations entitled to this isolation segment + description: Links to related resources +description: Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads. diff --git a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml index dfc532a991f..597d9da63d8 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of isolation segments resources: type: array items: $ref: './IsolationSegment.yaml' + description: List of isolation segments +description: A paginated list of isolation segments diff --git a/docs/openapi/apis/cf/latest/paths/Domains.yaml b/docs/openapi/apis/cf/latest/paths/Domains.yaml index 06bf38364ac..2115e074963 100644 --- a/docs/openapi/apis/cf/latest/paths/Domains.yaml +++ b/docs/openapi/apis/cf/latest/paths/Domains.yaml @@ -1,14 +1,27 @@ /v3/domains: get: summary: List domains - description: Retrieve all domains the user has access to. + description: |- + Retrieve all domains the user has access to. + + **Permitted roles:** All Roles operationId: listDomains tags: - Domains parameters: - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + - updated_at + - -updated_at + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml - $ref: ../components/parameters/LabelSelector.yaml @@ -18,21 +31,21 @@ type: array items: type: string - description: Comma-delimited list of GUIDs to filter by + description: Comma-delimited list of guids to filter by - name: names in: query schema: type: array items: type: string - description: Comma-delimited list of domain names to filter by + description: Comma-delimited list of domain names to filter by (case-insensitive) - name: organization_guids in: query schema: type: array items: type: string - description: Comma-delimited list of owning organization GUIDs to filter by + description: Comma-delimited list of owning organization guids to filter by responses: '200': description: OK @@ -48,20 +61,20 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/domains?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/domains?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/domains?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 created_at: '2019-03-08T01:06:19Z' updated_at: '2019-03-08T01:06:19Z' name: test-domain.com internal: false router_group: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 5806148f-cce6-4d86-7fbd-aa269e3f6f3f supported_protocols: - tcp metadata: @@ -79,6 +92,29 @@ href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations router_group: href: https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f + - guid: 9b2f3d89-3f89-4f05-8188-8a2b298c79d5 + created_at: '2026-04-21T10:15:30Z' + updated_at: '2026-04-21T10:15:30Z' + name: apps.identity + internal: false + router_group: null + supported_protocols: + - http + enforce_route_policies: true + route_policies_scope: org + metadata: + labels: {} + annotations: {} + relationships: + organization: + data: null + shared_organizations: + data: [] + links: + self: + href: https://api.example.org/v3/domains/9b2f3d89-3f89-4f05-8188-8a2b298c79d5 + route_reservations: + href: https://api.example.org/v3/domains/9b2f3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -97,7 +133,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a domain - description: Create a domain. + description: |- + Create a domain. + + **Permitted roles:** Admin, Org Manager *(when an `organization` relationship is provided)* operationId: createDomain tags: - Domains @@ -110,6 +149,38 @@ application/json: schema: $ref: ../components/schemas/Domain.yaml + examples: + default: + summary: default + value: + guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + name: test-domain.com + internal: false + router_group: null + supported_protocols: + - http + metadata: + labels: {} + annotations: {} + relationships: + organization: + data: + guid: 3a3f3d89-3f89-4f05-8188-751b298c79d5 + shared_organizations: + data: + - guid: 404f3d89-3f89-4a72-8188-751b298d88d5 + - guid: 416d3d89-3f89-4b67-a189-123b298d3592 + links: + self: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + organization: + href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5 + route_reservations: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations + shared_organizations: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations links: organization: operationId: getOrganization @@ -133,7 +204,10 @@ /v3/domains/{guid}: get: summary: Get a domain - description: Retrieve a domain. + description: |- + Retrieve a domain. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager *(can only view domains without an organization relationship)*, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getDomain tags: - Domains @@ -146,6 +220,38 @@ application/json: schema: $ref: ../components/schemas/Domain.yaml + examples: + default: + summary: default + value: + guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + name: test-domain.com + internal: false + router_group: null + supported_protocols: + - http + metadata: + labels: {} + annotations: {} + relationships: + organization: + data: + guid: 3a3f3d89-3f89-4f05-8188-751b298c79d5 + shared_organizations: + data: + - guid: 404f3d89-3f89-4a72-8188-751b298d88d5 + - guid: 416d3d89-3f89-4b67-a189-123b298d3592 + links: + self: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + organization: + href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5 + route_reservations: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations + shared_organizations: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations links: organization: operationId: getOrganization @@ -160,32 +266,17 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a domain - description: Update a domain. + description: |- + Update a domain. + + **Permitted roles:** Admin, Org Manager *(if domain is scoped to organization managed by the org manager)* operationId: updateDomain tags: - Domains parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: Domain object that needs to be updated - required: true - content: - application/json: - schema: - type: object - properties: - metadata: - $ref: ../components/schemas/Metadata.yaml - description: Request schema for updating a domain - examples: - default: - summary: default - value: - metadata: - labels: - key: value - annotations: - note: detailed information + $ref: ../components/requestBodies/DomainUpdateRequestBody.yaml responses: '200': description: Successfully updated domain @@ -193,6 +284,40 @@ application/json: schema: $ref: ../components/schemas/Domain.yaml + examples: + default: + summary: default + value: + guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + name: test-domain.com + internal: false + router_group: null + supported_protocols: + - http + metadata: + labels: + key: value + annotations: + note: detailed information + relationships: + organization: + data: + guid: 3a3f3d89-3f89-4f05-8188-751b298c79d5 + shared_organizations: + data: + - guid: 404f3d89-3f89-4a72-8188-751b298d88d5 + - guid: 416d3d89-3f89-4b67-a189-123b298d3592 + links: + self: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + organization: + href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5 + route_reservations: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations + shared_organizations: + href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -211,7 +336,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a domain - description: Delete a domain. + description: |- + Delete a domain. + + **Permitted roles:** Admin, Org Manager *(if domain is scoped to organization managed by the org manager)* operationId: deleteDomain tags: - Domains @@ -239,32 +367,38 @@ /v3/domains/{guid}/relationships/shared_organizations: post: summary: Share a domain - description: This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain. + description: |- + This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain. + + **Permitted roles:** Admin, Org Manager operationId: shareDomain tags: - Domains parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: List of organizations to share the domain with + description: The organization guids with which to share the domain required: true content: application/json: schema: type: object + required: + - data properties: data: type: array items: $ref: ../components/schemas/Relationship.yaml - description: Organization relationships; each organization will be entitled to manage this isolation segment + description: The organization guids with which to share the domain + description: A to-many relationship containing the organization guids with which to share the domain examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 404f3d89-3f89-4a72-8188-751b298d88d5 + - guid: 416d3d89-3f89-4b67-a189-123b298d3592 responses: '200': description: Successfully shared domain @@ -275,19 +409,16 @@ properties: data: type: array - items: - type: object - properties: - guid: - type: string - format: uuid + items: + $ref: ../components/schemas/Relationship.yaml + description: The organizations the domain is shared with examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 404f3d89-3f89-4a72-8188-751b298d88d5 + - guid: 416d3d89-3f89-4b67-a189-123b298d3592 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -303,21 +434,56 @@ Retrieve all domains available in an organization for the current user. This will return unscoped domains (those without an owning organization), domains that are scoped to the given organization (owned by the given organization), and domains that have been shared with the organization. To retrieve the default domain for an organization, use the [get default domain](#get-default-domain) endpoint. + + **Permitted roles:** All Roles operationId: listDomainsForOrganization tags: - Domains parameters: - - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The guid of the organization + - name: guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of guids to filter by - name: names in: query schema: type: array items: type: string - description: Comma-delimited list of domain names to filter by + description: Comma-delimited list of domain names to filter by (case-insensitive) + - name: organization_guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of owning organization guids to filter by + - $ref: ../components/parameters/Page.yaml + - $ref: ../components/parameters/PerPage.yaml + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + - updated_at + - -updated_at + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at` + - $ref: ../components/parameters/LabelSelector.yaml + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml responses: '200': description: OK @@ -333,20 +499,20 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5/domains?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5/domains?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5/domains?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 created_at: '2019-03-08T01:06:19Z' updated_at: '2019-03-08T01:06:19Z' name: test-domain.com internal: false router_group: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 5806148f-cce6-4d86-7fbd-aa269e3f6f3f supported_protocols: - tcp metadata: @@ -373,7 +539,10 @@ /v3/domains/{guid}/route_reservations: get: summary: Check reserved routes for a domain - description: Check if a specific route for a domain exists, regardless of the user’s visibility for the route in case the route belongs to a space the user does not belong to. + description: |- + Check if a specific route for a domain exists, regardless of the user's visibility for the route in case the route belongs to a space the user does not belong to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager *(can only check if routes exist for a domain without an organization relationship)*, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: checkReservedRoutesForDomain tags: - Domains @@ -381,19 +550,22 @@ - $ref: ../components/parameters/Guid.yaml - name: host in: query + required: false schema: type: string - description: Hostname to filter by + description: Hostname to filter by; defaults to empty string if not provided and only applicable to `http` routes - name: path in: query + required: false schema: type: string - description: Path to filter by + description: Path to filter by; defaults to empty string if not provided and only applicable to `http` routes - name: port in: query + required: false schema: type: integer - description: Port to filter by + description: Port to filter by; only applicable to `tcp` routes and required for `tcp` routes responses: '200': description: OK @@ -404,6 +576,7 @@ properties: matching_route: type: boolean + description: Whether a route matching the given host, path, and port exists for the domain examples: default: summary: default @@ -418,7 +591,10 @@ /v3/domains/{guid}/relationships/shared_organizations/{org_guid}: delete: summary: Unshare a domain - description: This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain. + description: |- + This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain. + + **Permitted roles:** Admin, Org Manager *(can be in either the domain's owning organization or the organization it has been shared to)* operationId: unshareDomain tags: - Domains @@ -430,7 +606,7 @@ schema: type: string format: uuid - description: The GUID of the organization to unshare the domain from + description: The guid of the organization to unshare the domain from responses: '204': description: Successfully unshared domain diff --git a/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml b/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml index 8cc67497399..373b0ef1fa6 100644 --- a/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml +++ b/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml @@ -1,14 +1,29 @@ /v3/isolation_segments: get: summary: List isolation segments - description: Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs. + description: |- + Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs. + + **Permitted roles:** All Roles operationId: listIsolationSegments tags: - Isolation Segments parameters: - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + - updated_at + - -updated_at + - name + - -name + description: Value to sort by; defaults to ascending. Prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`, and `name` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml - $ref: ../components/parameters/LabelSelector.yaml @@ -18,21 +33,21 @@ type: array items: type: string - description: Comma-delimited list of isolation segment guids to filter by. + description: Comma-delimited list of isolation segment guids to filter by - name: names in: query schema: type: array items: type: string - description: Comma-delimited list of isolation segment names to filter by. + description: Comma-delimited list of isolation segment names to filter by (case-insensitive) - name: organization_guids in: query schema: type: array items: type: string - description: Comma-delimited list of organization guids to filter by. + description: Comma-delimited list of organization guids to filter by responses: '200': description: OK @@ -55,7 +70,7 @@ href: https://api.example.org/v3/isolation_segments?page=2&per_page=5 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c name: an_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' @@ -67,7 +82,7 @@ metadata: annotations: {} labels: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac name: an_isolation_segment1 created_at: '2016-10-19T20:29:19Z' updated_at: '2016-11-08T16:41:26Z' @@ -79,7 +94,7 @@ metadata: annotations: {} labels: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: ecdc67c3-a71e-43ff-bddf-048930b8cd03 name: an_isolation_segment2 created_at: '2016-10-19T20:29:22Z' updated_at: '2016-11-08T16:41:26Z' @@ -91,7 +106,7 @@ metadata: annotations: {} labels: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 424c89e4-4353-46b7-9bf4-f90bd9bacac0 name: an_isolation_segment3 created_at: '2016-10-19T20:29:27Z' updated_at: '2016-11-08T16:41:26Z' @@ -103,7 +118,7 @@ metadata: annotations: {} labels: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 0a79fcec-a648-4eb8-a6c3-2b5be39047c7 name: an_isolation_segment4 created_at: '2016-10-19T20:29:33Z' updated_at: '2016-11-08T16:41:26Z' @@ -133,7 +148,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create an isolation segment - description: Create an isolation segment. + description: |- + Create an isolation segment. + + **Permitted roles:** Admin operationId: createIsolationSegment tags: - Isolation Segments @@ -150,7 +168,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c name: an_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' @@ -179,7 +197,10 @@ /v3/isolation_segments/{guid}: get: summary: Get an isolation segment - description: Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs. + description: |- + Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs. + + **Permitted roles:** All Roles operationId: getIsolationSegment tags: - Isolation Segments @@ -196,7 +217,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c name: an_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' @@ -216,7 +237,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update an isolation segment - description: Update an isolation segment. + description: |- + Update an isolation segment. + + **Permitted roles:** Admin operationId: updateIsolationSegment tags: - Isolation Segments @@ -232,9 +256,10 @@ properties: name: type: string - description: The name of the isolation segment + description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness metadata: $ref: ../components/schemas/Metadata.yaml + description: Labels and annotations applied to the isolation segment examples: default: summary: default @@ -251,8 +276,8 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 - name: <%= name %> + guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c + name: my_isolation_segment created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' links: @@ -281,7 +306,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete an isolation segment - description: An isolation segment cannot be deleted if it is entitled to any organization. + description: |- + An isolation segment cannot be deleted if it is entitled to any organization. + + **Permitted roles:** Admin operationId: deleteIsolationSegment tags: - Isolation Segments @@ -302,27 +330,31 @@ $ref: ../components/responses/500.yaml /v3/isolation_segments/{guid}/relationships/organizations: post: - summary: Entitle organizations for isolation segment - description: This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization. + summary: Entitle organizations for an isolation segment + description: |- + This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization. + + **Permitted roles:** Admin operationId: entitleOrganizationsForIsolationSegment tags: - Isolation Segments parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: List of organizations to entitle + description: Organization relationships; each organization will be entitled to manage this isolation segment required: true content: application/json: schema: $ref: ../components/schemas/RelationshipToMany.yaml + description: Organization relationships; each organization will be entitled to manage this isolation segment examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac + - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c responses: '200': description: OK @@ -335,8 +367,8 @@ summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac + - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c links: self: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations @@ -352,14 +384,15 @@ $ref: ../components/responses/UnprocessableEntity.yaml get: summary: List organizations relationship - description: This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs. + description: |- + This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs. + + **Permitted roles:** All Roles operationId: listOrganizationsForIsolationSegment tags: - Isolation Segments parameters: - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml responses: '200': description: OK @@ -372,8 +405,8 @@ summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac + - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c links: self: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations @@ -388,7 +421,10 @@ /v3/isolation_segments/{guid}/relationships/organizations/{org_guid}: delete: summary: Revoke entitlement to isolation segment for an organization - description: This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization’s default, the entitlement cannot be revoked. + description: |- + This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization's default, the entitlement cannot be revoked. + + **Permitted roles:** Admin operationId: revokeIsolationSegmentForOrganization tags: - Isolation Segments @@ -400,7 +436,7 @@ schema: type: string format: uuid - description: The GUID of the organization to revoke entitlement from. + description: The guid of the organization to revoke entitlement from responses: '204': description: No Content @@ -415,14 +451,15 @@ /v3/isolation_segments/{guid}/relationships/spaces: get: summary: List spaces relationship - description: This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access. + description: |- + This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access. + + **Permitted roles:** All Roles operationId: listSpacesForIsolationSegment tags: - Isolation Segments parameters: - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml responses: '200': description: OK @@ -435,8 +472,8 @@ summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f links: self: href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces @@ -449,14 +486,44 @@ /v3/isolation_segments/{guid}/organizations: get: summary: List organizations for isolation segment - description: This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs. + description: |- + Retrieve the organizations entitled to the isolation segment. Return only the organizations the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager, Org Manager operationId: listOrganizationsForIsolationSegmentShort tags: - Isolation Segments parameters: - $ref: ../components/parameters/Guid.yaml + - name: names + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of organization names to filter by (case-insensitive) + - name: guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of organization guids to filter by - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + - updated_at + - -updated_at + - name + - -name + description: Value to sort by; defaults to ascending. Prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`, and `name` responses: '200': description: OK @@ -478,7 +545,7 @@ next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: org1 @@ -495,11 +562,11 @@ relationships: quota: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b7887f5c-34bb-40c5-9778-577572e4fb2d metadata: labels: {} annotations: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f created_at: '2017-02-02T00:14:30Z' updated_at: '2017-02-02T00:14:30Z' name: org2 @@ -507,7 +574,7 @@ relationships: quota: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b7887f5c-34bb-40c5-9778-577572e4fb2d links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f