diff --git a/docs/openapi/.redocly.lint-ignore.yaml b/docs/openapi/.redocly.lint-ignore.yaml index e600f7e1e64..007981f29b6 100644 --- a/docs/openapi/.redocly.lint-ignore.yaml +++ b/docs/openapi/.redocly.lint-ignore.yaml @@ -1,5 +1,2 @@ # This file instructs Redocly's linter to ignore the rules contained for specific parts of your API. # See https://redocly.com/docs/cli/ for more information. -apis/cf/latest/paths/Packages.yaml: - operation-2xx-response: - - '#/~1v3~1packages~1{guid}~1download/get/responses' diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/AppCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/AppCreateRequestBody.yaml index b2fe58ec1b9..5048ac0dee6 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/AppCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/AppCreateRequestBody.yaml @@ -7,25 +7,31 @@ content: properties: name: type: string - description: Name of the app - environment_variables: - type: object - description: Environment variables to be used for the App when running - additionalProperties: - type: string - lifecycle: - $ref: ../schemas/Lifecycle.yaml - description: Provides the lifecycle object for the application + description: Name of the app; must be unique within the space (case-insensitive) relationships: type: object + description: Relationships to other resources properties: space: $ref: ../schemas/RelationshipToOne.yaml description: A relationship to a space required: - space + environment_variables: + type: object + description: Environment variables to be used for the App when running + default: {} + additionalProperties: + type: string + lifecycle: + $ref: ../schemas/Lifecycle.yaml + description: Provides the lifecycle object for the application; defaults to the [buildpack lifecycle](#buildpack-lifecycle-object) metadata: $ref: ../schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the app + + `annotations`: Annotations applied to the app required: - name - relationships @@ -38,4 +44,4 @@ content: relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/AppUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/AppUpdateRequestBody.yaml index 42003efcc26..7dcd6c04a59 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/AppUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/AppUpdateRequestBody.yaml @@ -8,16 +8,15 @@ content: name: type: string description: Name of the app - environment_variables: - type: object - description: Environment variables to be used for the App when running - additionalProperties: - type: string lifecycle: $ref: ../schemas/Lifecycle.yaml - description: Lifecycle to be used when updating the app; note `data` is a required field in lifecycle if lifecycle is updated. `type` may NOT be changed from its current value. + description: 'Lifecycle to be used when updating the app; note: `data` is a required field in lifecycle if lifecycle is updated. `type` may NOT be changed from its current value.' metadata: $ref: ../schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the app + + `annotations`: Annotations applied to the app description: Request schema for updating an app examples: default: diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/BuildCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/BuildCreateRequestBody.yaml index b37dac6ba3b..c86675e54f8 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/BuildCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/BuildCreateRequestBody.yaml @@ -11,14 +11,31 @@ content: guid: type: string format: uuid + description: The guid of the app package to stage required: - guid description: App package to stage lifecycle: $ref: '../schemas/Lifecycle.yaml' - description: Lifecycle information for a build + description: Lifecycle information for a build; defaults to the lifecycle on the app + staging_memory_in_mb: + type: integer + description: Memory in MB allocated for staging of the build + staging_disk_in_mb: + type: integer + description: Disk space in MB allocated for staging of the build + staging_log_rate_limit_bytes_per_second: + type: integer + description: Log rate limit in bytes per second allocated for staging of the build metadata: $ref: '../schemas/Metadata.yaml' + description: Labels and annotations applied to the build required: - package description: Request schema for creating a build + examples: + default: + summary: default + value: + package: + guid: 8e4da443-f255-499c-8b47-b3729b5b7432 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackCreateRequestBody.yaml index 75cfee6b555..f1b241f4463 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackCreateRequestBody.yaml @@ -7,24 +7,36 @@ content: properties: name: type: string - description: The name of the buildpack + description: Name of the buildpack; must be unique per stack (case-sensitive) stack: - type: string + type: [string, 'null'] + default: null description: The name of the stack that the buildpack will use position: type: integer + default: 1 description: The order in which the buildpacks are checked during buildpack auto-detection lifecycle: type: string + default: buildpack + enum: + - buildpack + - cnb description: The version of buildpack the buildpack will use. `buildpack` indicates [Classic Buildpacks](https://docs.cloudfoundry.org/buildpacks/classic.html). `cnb` indicates [Cloud Native Buildpacks](https://docs.cloudfoundry.org/buildpacks/cnb/) enabled: type: boolean + default: true description: Whether or not the buildpack will be used for staging locked: type: boolean + default: false description: Whether or not the buildpack is locked to prevent updating the bits metadata: $ref: ../schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the buildpack + + `annotations`: Annotations applied to the buildpack required: - name description: Request schema for creating a buildpack diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackUpdateRequestBody.yaml index 21b334b19e4..9ae6b8fe515 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/BuildpackUpdateRequestBody.yaml @@ -7,7 +7,10 @@ content: properties: name: type: string - description: The name of the buildpack + description: Name of the buildpack + stack: + type: [string, 'null'] + description: The name of the stack that the buildpack will use position: type: integer description: The order in which the buildpacks are checked during buildpack auto-detection @@ -17,11 +20,12 @@ content: locked: type: boolean description: Whether or not the buildpack is locked to prevent updating the bits - stack: - type: string - description: The name of the stack that the buildpack will use metadata: $ref: ../schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the buildpack + + `annotations`: Annotations applied to the buildpack description: Request schema for updating a buildpack examples: default: 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/DropletCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DropletCreateRequestBody.yaml index dd61f76db46..40a9a55ea7e 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/DropletCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/DropletCreateRequestBody.yaml @@ -1,4 +1,5 @@ -description: Droplet object that needs to be created +description: |- + Droplet object that needs to be created. When the `source_guid` query parameter is supplied the droplet is copied instead, and `relationships.app` (the destination app) is the only accepted parameter. required: true content: application/json: @@ -15,9 +16,11 @@ content: - app process_types: type: object - description: Process names and start commands for the droplet - metadata: - $ref: ../schemas/Metadata.yaml + additionalProperties: + type: string + default: + web: '' + description: Process names and start commands for the droplet; not accepted when copying a droplet required: - relationships description: Request schema for creating a droplet @@ -32,3 +35,10 @@ content: process_types: rake: bundle exec rake web: bundle exec rackup config.ru -p $PORT + copy: + summary: copy (with the source_guid query parameter) + value: + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/DropletUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DropletUpdateRequestBody.yaml new file mode 100644 index 00000000000..b5256bc84c6 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/requestBodies/DropletUpdateRequestBody.yaml @@ -0,0 +1,23 @@ +description: Droplet object that needs to be updated +required: true +content: + application/json: + schema: + type: object + properties: + metadata: + $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the droplet + image: + type: string + description: Image reference where the built complete image was stored (field can only be passed by Build State Updaters) + description: Request schema for updating a droplet + examples: + default: + summary: default + value: + metadata: + labels: + key: value + annotations: + note: detailed information diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/DropletUploadRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DropletUploadRequestBody.yaml new file mode 100644 index 00000000000..c5de00e51d0 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/requestBodies/DropletUploadRequestBody.yaml @@ -0,0 +1,17 @@ +description: A gzip compressed tarball file containing a Cloud Foundry compatible droplet, sent as part of a multi-part form +required: true +content: + multipart/form-data: + schema: + type: object + properties: + bits: + type: string + format: binary + description: A gzip compressed tarball file with `.tgz` extension containing the droplet bits + required: + - bits + description: Request schema for uploading droplet bits + encoding: + bits: + contentType: application/gzip 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/requestBodies/ManagedServiceInstanceUpdate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ManagedServiceInstanceUpdate.yaml index f781183c873..f5c3d2fd44f 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ManagedServiceInstanceUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ManagedServiceInstanceUpdate.yaml @@ -1,25 +1,32 @@ -description: Managed service instance to update +description: Optional parameters for updating a managed service instance +required: true content: application/json: schema: - type: object - properties: - name: - type: string - description: Name of the service instance - tags: - type: array - items: - type: string - description: Tags for the service instance - parameters: - type: object - description: Parameters for the service instance - relationships: - type: object - properties: + $ref: '../schemas/ManagedServiceInstanceUpdate.yaml' + examples: + managed_service_instance: + summary: Update managed service instance + value: + name: my_service_instance + parameters: + foo: bar + baz: qux + tags: + - foo + - bar + - baz + relationships: service_plan: - $ref: '../schemas/RelationshipToOne.yaml' - description: Relationships for the service instance - metadata: - $ref: '../schemas/Metadata.yaml' + data: + guid: f2b6ba9c-a4d2-11ea-8ae6-48bf6bec2d78 + metadata: + annotations: + note: detailed information + labels: + key: value + managed_service_instance_upgrade: + summary: Upgrade managed service instance (maintenance_info update) + value: + maintenance_info: + version: 2.1.1 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationCreateRequestBody.yaml index 8d94d804ead..7f22377fd83 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationCreateRequestBody.yaml @@ -4,18 +4,19 @@ content: application/json: schema: type: object + description: Request schema for creating an organization properties: name: type: string - description: Organization name + description: Organization name; must be unique (case-insensitive) suspended: type: boolean description: Whether an organization is suspended or not metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the organization required: - name - description: Request schema for creating an organization examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaCreateRequestBody.yaml index 79284632c38..61f37e9aeb0 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaCreateRequestBody.yaml @@ -4,90 +4,80 @@ content: application/json: schema: type: object + description: Request schema for creating an organization quota properties: name: type: string - description: Name of the quota + description: Name of the quota (case-insensitive) apps: type: object description: Quotas that affect applications and application sub-resources properties: per_process_memory_in_mb: - type: - - integer - - 'null' - description: Maximum memory for a single process or task + type: [integer, "null"] + default: null + description: Maximum memory for a single process or task; defaults to `null` (infinite) total_memory_in_mb: - type: - - integer - - 'null' - description: Total memory allowed for all the started processes and running tasks in an organization + type: [integer, "null"] + default: null + description: Total memory allowed for all the started processes and running tasks in an organization; defaults to `null` (infinite) total_instances: - type: - - integer - - 'null' - description: Total instances of all the started processes allowed in an organization + type: [integer, "null"] + default: null + description: Total instances of all the started processes allowed in an organization; defaults to `null` (infinite) log_rate_limit_in_bytes_per_second: - type: - - integer - - 'null' - description: Total log rate limit allowed for all the started processes and running tasks in an organization + type: [integer, "null"] + default: null + description: Total log rate limit allowed for all the started processes and running tasks in an organization; defaults to `null` (infinite) per_app_tasks: - type: - - integer - - 'null' - description: Maximum number of running tasks in an organization + type: [integer, "null"] + default: null + description: Maximum number of running tasks in an organization; defaults to `null` (infinite) services: type: object description: Quotas that affect services properties: paid_services_allowed: type: boolean - description: Specifies whether instances of paid service plans can be created + default: true + description: Specifies whether instances of paid service plans can be created; defaults to `true` total_service_instances: - type: - - integer - - 'null' - description: Total number of service instances allowed in an organization + type: [integer, "null"] + default: null + description: Total number of service instances allowed in an organization; defaults to `null` (infinite) total_service_keys: - type: - - integer - - 'null' - description: Total number of service keys allowed in an organization + type: [integer, "null"] + default: null + description: Total number of service keys allowed in an organization; defaults to `null` (infinite) routes: type: object description: Quotas that affect routes properties: total_routes: - type: - - integer - - 'null' - description: Total number of routes allowed in an organization + type: [integer, "null"] + default: null + description: Total number of routes allowed in an organization; defaults to `null` (infinite) total_reserved_ports: - type: - - integer - - 'null' - description: Total number of ports that are reservable by routes in an organization + type: [integer, "null"] + default: null + description: Total number of ports that are reservable by routes in an organization; defaults to `null` (infinite) domains: type: object description: Quotas that affect domains properties: total_domains: - type: - - integer - - 'null' - description: Total number of domains that can be scoped to an organization + type: [integer, "null"] + default: null + description: Total number of domains that can be scoped to an organization; defaults to `null` (infinite) relationships: type: object + description: Relationships for the organization quota properties: organizations: $ref: ../schemas/RelationshipToMany.yaml - description: A relationship to the organizations where the quota is applied - metadata: - $ref: ../schemas/Metadata.yaml + description: A relationship to the organizations where the quota is applied; defaults to an empty list required: - name - description: Request schema for creating an organization quota examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaUpdateRequestBody.yaml index 00d1402d878..1046f53bdf6 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationQuotaUpdateRequestBody.yaml @@ -4,6 +4,7 @@ content: application/json: schema: type: object + description: Request schema for updating an organization quota properties: name: type: string @@ -14,49 +15,66 @@ content: properties: per_process_memory_in_mb: type: [integer, "null"] - description: Maximum memory for a single process or task + description: Maximum memory for a single process or task; `null` means unlimited total_memory_in_mb: type: [integer, "null"] - description: Total memory allowed for all the started processes and running tasks in an organization + description: Total memory of all the started processes and running tasks in an organization; `null` means unlimited total_instances: type: [integer, "null"] - description: Total instances of all the started processes allowed in an organization + description: Total instances of all the started processes in an organization; `null` means unlimited log_rate_limit_in_bytes_per_second: type: [integer, "null"] - description: Total log rate limit allowed for all the started processes and running tasks in an organization + description: Total log rate limit allowed for all the started processes and running tasks in an organization; `null` means unlimited per_app_tasks: type: [integer, "null"] - description: Maximum number of running tasks in an organization + description: Maximum number of running tasks in an organization; `null` means unlimited services: type: object description: Quotas that affect services properties: paid_services_allowed: type: boolean - description: Specifies whether instances of paid service plans can be created + description: If instances of paid service plans can be created total_service_instances: type: [integer, "null"] - description: Total number of service instances allowed in an organization + description: Total number of service instances in an organization; `null` means unlimited total_service_keys: type: [integer, "null"] - description: Total number of service keys allowed in an organization + description: Total number of service keys in an organization; `null` means unlimited routes: type: object description: Quotas that affect routes properties: total_routes: type: [integer, "null"] - description: Total number of routes allowed in an organization + description: Total number of routes that an organization can have; `null` means unlimited total_reserved_ports: type: [integer, "null"] - description: Total number of ports that are reservable by routes in an organization + description: Total number of ports that all routes in an organization can reserve; `null` means unlimited domains: type: object description: Quotas that affect domains properties: total_domains: type: [integer, "null"] - description: Total number of domains that can be scoped to an organization - metadata: - $ref: '../schemas/Metadata.yaml' - description: Request schema for updating an organization quota + description: Total number of domains that can be scoped to an organization; `null` means unlimited + examples: + default: + summary: default + value: + name: don-quixote + apps: + total_memory_in_mb: 5120 + per_process_memory_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + total_instances: 10 + per_app_tasks: 5 + services: + paid_services_allowed: true + total_service_instances: 10 + total_service_keys: 20 + routes: + total_routes: 8 + total_reserved_ports: 4 + domains: + total_domains: 7 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationUpdateRequestBody.yaml index 3cec99e5c4c..f26789f90f5 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/OrganizationUpdateRequestBody.yaml @@ -4,6 +4,7 @@ content: application/json: schema: type: object + description: Request schema for updating an organization properties: name: type: string @@ -13,7 +14,7 @@ content: description: Whether an organization is suspended or not metadata: $ref: ../schemas/Metadata.yaml - description: Request schema for updating an organization + description: Labels and annotations applied to the organization examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/PackageCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/PackageCreateRequestBody.yaml index cd608374c42..a69a6259ca7 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/PackageCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/PackageCreateRequestBody.yaml @@ -1,4 +1,5 @@ -description: Package object that needs to be created or copied. When copying (source_guid query parameter is provided), only relationships.app is required. When creating a new package, type and relationships.app are required. +description: |- + Package object that needs to be created. When the `source_guid` query parameter is supplied the package is copied instead, and `relationships.app` (the destination app) is the only accepted parameter. required: true content: application/json: @@ -7,36 +8,38 @@ content: properties: type: type: string - description: Type of the package; valid values are bits or docker. Required when creating a new package (when source_guid is not provided). Not required when copying a package (when source_guid is provided). + description: Type of the package; valid values are `bits`, `docker`. Required when creating a package; not accepted when copying a package (when `source_guid` is supplied) enum: - bits - docker + relationships: + type: object + properties: + app: + $ref: ../schemas/RelationshipToOne.yaml + description: A relationship to an app + required: + - app data: type: object - description: Data for package type + default: {} + description: Data for package type; not accepted when copying a package properties: image: type: string - description: The registry address of the image (for docker packages) + description: Required when `type` is `docker`; the registry address of the image username: type: string - description: The username for the image's registry (for docker packages) + description: Optional when `type` is `docker` and accessing a secured registry password: type: string - description: The password for the image's registry (for docker packages) - relationships: - type: object - properties: - app: - $ref: ../schemas/RelationshipToOne.yaml - description: A relationship to an app - required: - - app + description: Optional when `type` is `docker` and accessing a secured registry metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the package required: - relationships - description: Request schema for creating a package + description: Request schema for creating or copying a package examples: buildpack_app: summary: buildpack app @@ -58,3 +61,10 @@ content: image: registry/image:latest username: username password: password + copy: + summary: copy (with the source_guid query parameter) + value: + relationships: + app: + data: + guid: 36208a68-562d-4f51-94ea-28bd8553a271 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/PackageUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/PackageUpdateRequestBody.yaml index bd3c8f494db..1924711042f 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/PackageUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/PackageUpdateRequestBody.yaml @@ -7,10 +7,20 @@ content: properties: metadata: $ref: '../schemas/Metadata.yaml' + description: Labels and annotations applied to the package username: type: string - description: The username for the image’s registry. Only possible for Docker package. + description: The username for the image's registry. Only possible for Docker package. password: type: string - description: The password for the image’s registry. Only possible for Docker package. + description: The password for the image's registry. Only possible for Docker package. description: Request schema for updating a package + examples: + default: + summary: default + value: + metadata: + labels: + key: value + annotations: + note: detailed information diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/PackageUploadRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/PackageUploadRequestBody.yaml index 56c0550f486..3d333b8d8b4 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/PackageUploadRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/PackageUploadRequestBody.yaml @@ -1,4 +1,5 @@ -description: Package bits to be uploaded +description: |- + A multi-part form for packages of type `bits`. The request requires either a [.zip file](https://en.wikipedia.org/wiki/Zip_(file_format)) uploaded under the `bits` field or a list of [resource match objects](#the-resource-match-object) under the `resources` field. These field may be used together. required: true content: multipart/form-data: @@ -8,7 +9,16 @@ content: bits: type: string format: binary + description: A binary zip file containing the package bits resources: type: array + default: [] + description: Fingerprints of the application bits that have previously been pushed to Cloud Foundry, formatted as [resource match objects](#the-resource-match-object). This field accepts the v2 resources object format. items: - $ref: '../schemas/ResourceMatch.yaml' + $ref: '../schemas/ResourceMatchObject.yaml' + description: Request schema for uploading package bits + encoding: + bits: + contentType: application/zip + resources: + contentType: application/json diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ProcessScaleRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ProcessScaleRequestBody.yaml new file mode 100644 index 00000000000..1a2ae574ada --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ProcessScaleRequestBody.yaml @@ -0,0 +1,36 @@ +description: The desired scale for the process +required: true +content: + application/json: + schema: + type: object + properties: + instances: + type: + - integer + - 'null' + description: The number of instances to run + memory_in_mb: + type: + - integer + - 'null' + 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 in bytes per second allocated per instance + description: Request schema for scaling a process + examples: + default: + summary: default + value: + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ProcessUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ProcessUpdateRequestBody.yaml index 2cb1fa1719d..67aa19fd4bd 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ProcessUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ProcessUpdateRequestBody.yaml @@ -14,10 +14,11 @@ content: $ref: ../schemas/HealthCheck.yaml description: The health check to perform on the process readiness_health_check: - $ref: ../schemas/HealthCheck.yaml + $ref: ../schemas/ReadinessHealthCheck.yaml description: The readiness health check to perform on the process metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the process description: Request schema for updating a process examples: default: diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/RoleCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/RoleCreate.yaml index 22d81bac146..04b5f4de10f 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/RoleCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/RoleCreate.yaml @@ -3,10 +3,13 @@ content: application/json: schema: type: object + required: + - type + - relationships properties: type: type: string - description: Role to create + description: Role to create; see [valid role types](#valid-role-types) enum: - organization_user - organization_auditor @@ -18,9 +21,19 @@ content: - space_supporter relationships: type: object + description: |- + Relationships for the role. `user` is always required. Exactly one of `organization` (when creating an organization role) or `space` (when creating a space role) must also be provided. + required: + - user + oneOf: + - required: + - organization + - required: + - space properties: user: $ref: ../schemas/UserRelationshipToOne.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) organization: $ref: ../schemas/RelationshipToOne.yaml description: A relationship to an organization; required only when creating an organization role @@ -35,10 +48,10 @@ content: relationships: user: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 47c5da3b-6cbc-421c-87c3-20bb3c41ab7c organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 by_username_and_origin: summary: by username and origin value: @@ -50,4 +63,15 @@ content: origin: ldap organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 + space_role: + summary: space role + value: + type: space_developer + relationships: + user: + data: + guid: 47c5da3b-6cbc-421c-87c3-20bb3c41ab7c + space: + data: + guid: 12347c70-d1bd-4976-a2ab-a85f5e882418 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/RouteCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/RouteCreateRequestBody.yaml index 9a464319ffa..18a8ee293ba 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/RouteCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/RouteCreateRequestBody.yaml @@ -1,4 +1,5 @@ description: Route to create +required: true content: application/json: schema: @@ -22,8 +23,16 @@ content: space: $ref: ../schemas/RelationshipToOne.yaml description: A relationship to the space containing the route; routes can only be mapped to destinations in that space + required: + - domain + - space + description: Relationships to the space and domain of the route + options: + $ref: ../schemas/RouteOptions.yaml + description: Options applied to the route metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the route required: - relationships examples: @@ -36,10 +45,10 @@ content: relationships: domain: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 0b5f3633-194c-42d2-9408-972366617e0e space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 options: loadbalancing: round-robin metadata: @@ -47,3 +56,19 @@ content: key: value annotations: note: detailed information + hash-based-routing: + summary: Example with hash-based routing + description: Creates a route that uses hash-based routing on the `X-User-ID` header with a load balance factor of 5.0. + value: + host: user-specific-app + relationships: + domain: + data: + guid: 0b5f3633-194c-42d2-9408-972366617e0e + space: + data: + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 + options: + loadbalancing: hash + hash_header: X-User-ID + hash_balance: '5.0' diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/RouteDestinations.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/RouteDestinations.yaml index 83a6be6a6eb..e2f52829a07 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/RouteDestinations.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/RouteDestinations.yaml @@ -1,4 +1,5 @@ description: A list of route destinations +required: true content: application/json: schema: @@ -6,19 +7,36 @@ content: properties: destinations: type: array + minItems: 0 + maxItems: 100 items: - $ref: ../schemas/RouteDestination.yaml + $ref: ../schemas/RouteDestinationRequest.yaml description: List of destinations to add to route; destinations without `process.type` specified will get process type `"web"` by default + required: + - destinations examples: default: summary: default value: destinations: - app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 + - app: + guid: 01856e12-8ee8-11e9-98a5-bb397dbc818f + process: + type: api + port: 9000 + protocol: http1 + weighted: + summary: Weighted destinations (deprecated) + description: Weighted destinations may only be supplied when replacing all destinations with `PATCH`; weights must sum to 100. + value: + destinations: + - app: + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 weight: 61 - app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 01856e12-8ee8-11e9-98a5-bb397dbc818f process: type: api weight: 39 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/requestBodies/ServiceBrokerCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerCreate.yaml index 394a3f90481..8cd7c1f1ee8 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerCreate.yaml @@ -1,4 +1,5 @@ description: Service broker to create +required: true content: application/json: schema: @@ -6,44 +7,28 @@ content: properties: name: type: string - description: Name of the service broker + description: Name of the service broker; must be unique (case-sensitive) url: type: string format: uri description: URL of the service broker authentication: - type: object - properties: - type: - type: string - enum: - - basic - description: Type of authentication - credentials: - type: object - properties: - username: - type: string - password: - type: string - required: - - username - - password - required: - - type - - credentials - description: Authentication details for the service broker + $ref: ../schemas/ServiceBrokerAuthentication.yaml + description: Credentials used to authenticate against the service broker relationships: type: object + description: Relationships for the service broker properties: space: $ref: ../schemas/RelationshipToOne.yaml - description: Relationships for the service broker + description: If set, restricts the service broker to the specified space metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the service broker required: - name - url + - authentication examples: default: summary: default @@ -58,4 +43,4 @@ content: relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerUpdateRequestBody.yaml index 9c84419329c..130732ea215 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceBrokerUpdateRequestBody.yaml @@ -10,34 +10,14 @@ content: description: Name of the service broker url: type: string + format: uri description: URL of the service broker authentication: - type: object + $ref: ../schemas/ServiceBrokerAuthentication.yaml description: Credentials used to authenticate against the service broker - properties: - type: - type: string - enum: - - basic - description: Authentication type - credentials: - type: object - description: Authentication credentials - properties: - username: - type: string - description: Username for basic authentication - password: - type: string - description: Password for basic authentication - required: - - username - - password - required: - - type - - credentials metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the service broker examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingCreateRequestBody.yaml index ed61657f4b1..212790cd86b 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingCreateRequestBody.yaml @@ -1,4 +1,5 @@ description: A request to create a service credential binding +required: true content: application/json: schema: @@ -12,10 +13,10 @@ content: enum: - app - key - description: Type of the service credential binding. Valid values are key and app + description: Type of the service credential binding. Valid values are `key` and `app` name: type: string - description: Name of the service credential binding. name is optional when the type is app + description: Name of the service credential binding. `name` is optional when the type is `app` relationships: type: object required: @@ -26,13 +27,22 @@ content: description: The service instance to be bound app: $ref: ../schemas/RelationshipToOne.yaml - description: The app to be bound. Required when type is app + description: The app to be bound. Required when type is `app` description: Relationships for the service credential binding + strategy: + type: string + enum: + - single + - multiple + default: single + description: Strategy for creating the service credential binding. Valid values are `single` (default) and `multiple` (experimental). Only valid when type is `app`. parameters: type: object + additionalProperties: true description: A JSON object that is passed to the service broker metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the service credential binding examples: app_credential_binding: summary: App credential binding diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingUpdateRequestBody.yaml index eac9848914e..e50addda15e 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceCredentialBindingUpdateRequestBody.yaml @@ -1,4 +1,5 @@ description: A request to update a service credential binding +required: true content: application/json: schema: @@ -6,6 +7,7 @@ content: properties: metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the service credential binding examples: update_binding: summary: Update service credential binding diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceCreateRequestBody.yaml index c0fcd478054..5f911c69953 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceCreateRequestBody.yaml @@ -1,53 +1,19 @@ -description: A request to create a service instance +description: |- + A request to create a service instance. + + Service instances can be of type `managed` or `user-provided`, and the required parameters are different for each type. +required: true content: application/json: schema: - type: object - required: - - type - - name - - relationships - properties: - type: - type: string - enum: - - managed - - user-provided - description: The type of service instance - name: - type: string - description: Name of the service instance - parameters: - type: object - description: A JSON object that is passed to the service broker - credentials: - type: object - description: A JSON object that is made available to apps bound to this service instance (user-provided services only) - tags: - type: array - items: - type: string - description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env - syslog_drain_url: - type: string - description: URL to which logs for bound applications will be streamed (user-provided services only) - route_service_url: - type: string - description: URL to which requests for bound routes will be forwarded; must use the https protocol (user-provided services only) - relationships: - type: object - required: - - space - properties: - space: - $ref: ../schemas/RelationshipToOne.yaml - description: The space in which to create the service instance - service_plan: - $ref: ../schemas/RelationshipToOne.yaml - description: The service plan from which to create the service instance - description: Relationships for the service instance - metadata: - $ref: ../schemas/Metadata.yaml + oneOf: + - $ref: ../schemas/ManagedServiceInstanceCreate.yaml + - $ref: ../schemas/UserProvidedServiceInstanceCreate.yaml + discriminator: + propertyName: type + mapping: + managed: ../schemas/ManagedServiceInstanceCreate.yaml + user-provided: ../schemas/UserProvidedServiceInstanceCreate.yaml examples: managed_service_instance: summary: Managed service instance diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceUpdateRequestBody.yaml index 2a6a50eb95c..fccc38c91c0 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServiceInstanceUpdateRequestBody.yaml @@ -1,47 +1,14 @@ -description: A request to update a service instance +description: |- + A request to update a service instance. + + The permitted parameters differ between `managed` and `user-provided` service instances. +required: true content: application/json: schema: - type: object - properties: - name: - type: string - description: Name of the service instance - parameters: - type: object - description: A JSON object that is passed to the service broker (managed services only) - credentials: - type: object - description: A JSON object that is made available to apps bound to this service instance (user-provided services only) - tags: - type: array - items: - type: string - description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env - syslog_drain_url: - type: string - description: URL to which logs for bound applications will be streamed (user-provided services only) - route_service_url: - type: string - description: URL to which requests for bound routes will be forwarded; must use the https protocol (user-provided services only) - relationships: - type: object - properties: - service_plan: - $ref: ../schemas/RelationshipToOne.yaml - description: The service plan from which to create the service instance - description: Relationships for the service instance - maintenance_info: - type: object - required: - - version - properties: - version: - type: string - description: Must be a semantic version value and it must match the version in the maintenance_info for the service instance plan in the updated broker catalog - description: If provided, must have the `version` field; `version` must be a semantic version value and it must match the `version` in the `maintenance_info` for the service instance plan in the updated broker catalog. Any other value for `version` will cause a `MaintenanceInfoConflict` error - metadata: - $ref: ../schemas/Metadata.yaml + anyOf: + - $ref: ../schemas/ManagedServiceInstanceUpdate.yaml + - $ref: ../schemas/UserProvidedServiceInstanceUpdate.yaml examples: managed_service_instance: summary: Update managed service instance @@ -64,7 +31,7 @@ content: labels: key: value managed_service_instance_upgrade: - summary: Upgrade managed service instance + summary: Upgrade managed service instance (maintenance_info update) value: maintenance_info: version: 2.1.1 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityCreateRequestBody.yaml index 5b083db443d..35a3c6883a3 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityCreateRequestBody.yaml @@ -1,4 +1,4 @@ -description: Service plan visibility object that needs to be created +description: Service plan visibility to apply required: true content: application/json: @@ -11,18 +11,19 @@ content: - public - admin - organization - description: Denotes the visibility of the plan + description: Denotes the visibility of the plan; can be `public`, `admin`, `organization`, see [_list of visibility types_](#list-of-visibility-types) organizations: type: array + description: Desired list of organizations GUIDs where the plan will be accessible; required if `type` is `organization` items: type: object properties: guid: type: string format: uuid + description: Unique identifier for the organization where the plan will be available required: - guid - description: Desired list of organizations GUIDs where the plan will be accessible; required if type is organization required: - type examples: @@ -31,4 +32,4 @@ content: value: type: organization organizations: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 0fc1ad4f-e1d7-4436-8e23-6b20f03c6482 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityUpdateRequestBody.yaml index 5aa583fa0b4..97728797cd0 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/ServicePlanVisibilityUpdateRequestBody.yaml @@ -7,18 +7,29 @@ content: properties: type: type: string - enum: [public, admin, organization] - description: Denotes the visibility of the plan + enum: + - public + - admin + - organization + description: Denotes the visibility of the plan; can be `public`, `admin`, `organization`, see [_list of visibility types_](#list-of-visibility-types) organizations: type: array + description: Desired list of organizations GUIDs where the plan will be accessible; required if `type` is `organization` items: type: object properties: guid: type: string format: uuid + description: Unique identifier for the organization where the plan will be available required: - guid - description: Desired list of organizations GUIDs where the plan will be accessible; required if type is organization required: - type + examples: + default: + summary: default + value: + type: organization + organizations: + - guid: 0fc1ad4f-e1d7-4436-8e23-6b20f03c6482 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SidecarCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SidecarCreate.yaml index 93fe203fd59..c6576e5a1ff 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SidecarCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/SidecarCreate.yaml @@ -1,23 +1,9 @@ -description: Sidecar to create +description: The sidecar to create +required: true content: application/json: schema: - type: object - properties: - name: - type: string - description: Name of the sidecar - command: - type: string - description: Command to run for the sidecar - process_types: - type: array - items: - type: string - description: Process types that the sidecar applies to - memory_in_mb: - type: integer - description: Memory limit for the sidecar in MB + $ref: ../schemas/SidecarCreate.yaml examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SidecarUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SidecarUpdateRequestBody.yaml index 359fdea9fc0..4269fc80330 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SidecarUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/SidecarUpdateRequestBody.yaml @@ -1,4 +1,4 @@ -description: Sidecar object that needs to be updated +description: The sidecar fields to update required: true content: application/json: @@ -17,8 +17,9 @@ content: type: string description: A list of process types the sidecar applies to memory_in_mb: - type: integer + type: [integer, "null"] description: Reserved memory for sidecar + description: Request schema for updating a sidecar examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreate.yaml deleted file mode 100644 index 25e92a53d31..00000000000 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreate.yaml +++ /dev/null @@ -1,20 +0,0 @@ -description: Space to create -content: - application/json: - schema: - type: object - properties: - name: - type: string - description: Name of the space - relationships: - type: object - properties: - organization: - $ref: '../schemas/RelationshipToOne.yaml' - description: The organization that the space belongs to - metadata: - $ref: '../schemas/Metadata.yaml' - required: - - name - - relationships diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreateRequestBody.yaml index 7c94c457b42..829fb69a9b3 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceCreateRequestBody.yaml @@ -4,12 +4,17 @@ content: application/json: schema: type: object + description: Request schema for creating a space properties: name: type: string - description: Name of the space + description: Space name; must be unique within the organization (case-insensitive) + suspended: + type: boolean + description: Whether a space is suspended or not relationships: type: object + description: Relationships for the space properties: organization: $ref: ../schemas/RelationshipToOne.yaml @@ -18,10 +23,10 @@ content: - organization metadata: $ref: ../schemas/Metadata.yaml + description: Labels and annotations applied to the space required: - name - relationships - description: Request schema for creating a space examples: default: summary: default @@ -30,4 +35,4 @@ content: relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e00705b9-7b42-4561-ae97-2520399d2133 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaCreate.yaml index bbc75bdc035..706900f66bc 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaCreate.yaml @@ -1,66 +1,80 @@ description: Space quota to create +required: true content: application/json: schema: type: object + required: + - name + - relationships properties: name: type: string - description: Name of the space quota + description: Name of the quota; must be unique within the organization (case-sensitive) apps: type: object + description: Quotas that affect applications and application sub-resources properties: total_memory_in_mb: - type: integer - description: Total memory allowed for all apps in MB + type: [integer, "null"] + default: null + description: Total memory allowed for all the started processes and running tasks in a space; defaults to `null` (infinite) per_process_memory_in_mb: - type: integer - description: Maximum memory per process in MB + type: [integer, "null"] + default: null + description: Maximum memory for a single process or task; defaults to `null` (infinite) log_rate_limit_in_bytes_per_second: - type: integer - description: Log rate limit in bytes per second + type: [integer, "null"] + default: null + description: Total log rate limit allowed for all the started processes and running tasks in an organization; defaults to `null` (infinite) total_instances: - type: integer - description: Total number of app instances allowed + type: [integer, "null"] + default: null + description: Total instances of all the started processes allowed in a space; defaults to `null` (infinite) per_app_tasks: - type: integer - description: Maximum number of tasks per app - description: App limits for the space quota + type: [integer, "null"] + default: null + description: Maximum number of running tasks in a space; defaults to `null` (infinite) services: type: object + description: Quotas that affect services properties: paid_services_allowed: type: boolean - description: Whether paid services are allowed + default: true + description: Specifies whether instances of paid service plans can be created total_service_instances: - type: integer - description: Total number of service instances allowed + type: [integer, "null"] + default: null + description: Total number of service instances allowed in a space; defaults to `null` (infinite) total_service_keys: - type: integer - description: Total number of service keys allowed - description: Service limits for the space quota + type: [integer, "null"] + default: null + description: Total number of service keys allowed in a space; defaults to `null` (infinite) routes: type: object + description: Quotas that affect routes properties: total_routes: - type: integer - description: Total number of routes allowed + type: [integer, "null"] + default: null + description: Total number of routes allowed in a space; defaults to `null` (infinite) total_reserved_ports: - type: integer - description: Total number of reserved ports allowed - description: Route limits for the space quota + type: [integer, "null"] + default: null + description: Total number of ports that are reservable by routes in a space; defaults to `null` (infinite) relationships: type: object + description: Relationships for the space quota + required: + - organization properties: organization: $ref: ../schemas/RelationshipToOne.yaml + description: A relationship to the organization where the quota belongs spaces: $ref: ../schemas/RelationshipToMany.yaml - description: Relationships for the space quota - metadata: - $ref: ../schemas/Metadata.yaml - required: - - name + description: A relationship to the spaces where the quota is applied examples: default: summary: default @@ -69,4 +83,4 @@ content: relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9b370018-c38e-44c9-86d6-155c76801104 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaUpdate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaUpdate.yaml index fcbd6a31ce9..2bfa2b9ba8d 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceQuotaUpdate.yaml @@ -1,53 +1,24 @@ description: Space quota to update +required: true content: application/json: schema: - type: object - properties: - name: - type: string - description: Name of the space quota - apps: - type: object - properties: - total_memory_in_mb: - type: integer - description: Total memory allowed for all apps in MB - per_process_memory_in_mb: - type: integer - description: Maximum memory per process in MB - log_rate_limit_in_bytes_per_second: - type: integer - description: Log rate limit in bytes per second - total_instances: - type: integer - description: Total number of app instances allowed - per_app_tasks: - type: integer - description: Maximum number of tasks per app - description: App limits for the space quota - services: - type: object - properties: - paid_services_allowed: - type: boolean - description: Whether paid services are allowed - total_service_instances: - type: integer - description: Total number of service instances allowed - total_service_keys: - type: integer - description: Total number of service keys allowed - description: Service limits for the space quota - routes: - type: object - properties: - total_routes: - type: integer - description: Total number of routes allowed - total_reserved_ports: - type: integer - description: Total number of reserved ports allowed - description: Route limits for the space quota - metadata: - $ref: '../schemas/Metadata.yaml' \ No newline at end of file + $ref: '../schemas/SpaceQuotaUpdate.yaml' + examples: + default: + summary: default + value: + name: don-quixote + apps: + total_memory_in_mb: 5120 + per_process_memory_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + total_instances: 10 + per_app_tasks: 5 + services: + paid_services_allowed: true + total_service_instances: 10 + total_service_keys: 20 + routes: + total_routes: 8 + total_reserved_ports: 4 diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceUpdateRequestBody.yaml index 55ebcbe7d30..61f5f4c2f82 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/SpaceUpdateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/SpaceUpdateRequestBody.yaml @@ -4,13 +4,17 @@ content: application/json: schema: type: object + description: Request schema for updating a space properties: name: type: string description: New space name + suspended: + type: boolean + description: Whether a space is suspended or not metadata: $ref: ../schemas/Metadata.yaml - description: Request schema for updating a space + description: Labels and annotations applied to the space examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml index 758be34716b..01c4275e961 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/StackCreateRequestBody.yaml @@ -7,13 +7,34 @@ content: properties: name: type: string - description: Name of the stack; must be unique and no longer than 250 characters maxLength: 250 + description: Name of the stack; must be unique (case-sensitive) and no longer than 250 characters description: type: [string, "null"] - description: Description of the stack; must no longer than 250 characters maxLength: 250 + default: null + description: Description of the stack; must no longer than 250 characters + state: + type: string + enum: + - ACTIVE + - RESTRICTED + - DEPRECATED + - DISABLED + description: 'The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`' + state_reason: + type: [string, "null"] + description: Optional plain text describing the stack state change metadata: $ref: '../schemas/Metadata.yaml' + description: Labels and annotations applied to the stack required: - name + examples: + default: + summary: default + value: + name: my-stack + description: Here is my stack! + state: ACTIVE + state_reason: null diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/TaskCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/TaskCreateRequestBody.yaml index a71aba038b1..82827ee2974 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/TaskCreateRequestBody.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/TaskCreateRequestBody.yaml @@ -1,4 +1,4 @@ -description: Task object that needs to be created +description: The task to create required: true content: application/json: @@ -7,43 +7,68 @@ content: properties: command: type: string - description: The command to run for the task. **NOTE:** optional if a `template.process.guid` is provided + description: |- + Command that will be executed; **NOTE:** optional if a `template.process.guid` is provided. + + If not provided, and a `template.process.guid` is provided, this field will use the value from the process with the given guid. name: type: string - description: Human-readable name for the task - memory_in_mb: - type: integer - description: Amount of memory to allocate for the task in MB + description: Name of the task; defaults to an auto-generated name + user: + type: string + description: OS user used to run the task in the runtime + default: vcap disk_in_mb: type: integer - description: Amount of disk to allocate for the task in MB + description: |- + Amount of disk to allocate for the task in MB; defaults to the operator-configured `default_app_disk_in_mb`. + + If not provided, and a `template.process.guid` is provided, this field will use the value from the process with the given guid. + memory_in_mb: + type: integer + description: |- + Amount of memory to allocate for the task in MB; defaults to the operator-configured `default_app_memory`. + + If not provided, and a `template.process.guid` is provided, this field will use the value from the process with the given guid. log_rate_limit_in_bytes_per_second: type: integer - description: Amount of log rate limit to allocate for the task in bytes per second + description: |- + Amount of log rate to allocate for the task in bytes; defaults to the operator-configured `default_app_log_rate_limit_in_bytes_per_second`. + + If not provided, and a `template.process.guid` is provided, this field will use the value from the process with the given guid. droplet_guid: type: string format: uuid - description: The GUID of a droplet to use to run the task + description: The guid of the droplet that will be used to run the command; defaults to the app's current droplet template: type: object - description: An object with a process field to template the task from + description: An object that describes a process to template the task from properties: process: type: object + description: The process that will be used as a template properties: guid: type: string format: uuid + description: The guid of the process that will be used as a template; defaults to `null` required: - guid - description: The guid of the process that will be used as a template metadata: $ref: ../schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the package + + `annotations`: Annotations applied to the package description: Request schema for creating a task examples: default: - summary: default + summary: with command + value: + command: rake db:migrate + template: + summary: with template process value: template: process: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 89323d4e-2e84-43e7-83e9-adbf50a20c0e diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/UserCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/UserCreate.yaml index 395b9f6d249..6672e10c194 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/UserCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/UserCreate.yaml @@ -1,25 +1,14 @@ description: User to create +required: true content: application/json: schema: - type: object - properties: - guid: - type: string - description: Unique identifier for the user - username: - type: string - description: Username of the user to be created. This can only be provided together with origin - origin: - type: string - description: Origin of the user to be created. This can only be provided together with username and cannot be uaa - metadata: - $ref: ../schemas/Metadata.yaml + $ref: ../schemas/UserCreate.yaml examples: default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 by_username_and_origin: summary: by username and origin value: diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/UserProvidedServiceInstanceUpdate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/UserProvidedServiceInstanceUpdate.yaml index 9d5fa5ca866..305dca5506b 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/UserProvidedServiceInstanceUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/UserProvidedServiceInstanceUpdate.yaml @@ -1,27 +1,25 @@ -description: User provided service instance to update +description: Optional parameters for updating a user-provided service instance +required: true content: application/json: schema: - type: object - properties: - name: - type: string - description: Name of the service instance - tags: - type: array - items: - type: string - description: Tags for the service instance - credentials: - type: object - description: Service credentials - syslog_drain_url: - type: string - format: uri - description: URL for syslog drain - route_service_url: - type: string - format: uri - description: URL for route service - metadata: - $ref: '../schemas/Metadata.yaml' + $ref: '../schemas/UserProvidedServiceInstanceUpdate.yaml' + examples: + user_provided_service_instance: + summary: Update user-provided service instance + value: + name: my_service_instance + credentials: + foo: bar + baz: qux + tags: + - foo + - bar + - baz + syslog_drain_url: https://syslog.com/drain + route_service_url: https://route.com/service + metadata: + annotations: + foo: bar + labels: + baz: qux diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/UserUpdate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/UserUpdate.yaml index 078c9d60866..255b458da36 100644 --- a/docs/openapi/apis/cf/latest/components/requestBodies/UserUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/requestBodies/UserUpdate.yaml @@ -1,26 +1,13 @@ description: User to update +required: true content: application/json: schema: type: object properties: - username: - type: string - description: The username of the user - presentation_name: - type: string - description: The presentation name of the user - origin: - type: string - description: The origin of the user metadata: $ref: ../schemas/Metadata.yaml - links: - type: object - properties: - self: - $ref: ../schemas/Link.yaml - description: The URL to get this user + description: Labels applied to and annotations added to the user examples: default: summary: default @@ -30,5 +17,3 @@ content: environment: production annotations: note: detailed information - rate_limits: - custom_request_limit: 2000 diff --git a/docs/openapi/apis/cf/latest/components/responses/BuildpackCreateResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/BuildpackCreateResponse.yaml index 24432dc09e0..b1c185bbff2 100644 --- a/docs/openapi/apis/cf/latest/components/responses/BuildpackCreateResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/BuildpackCreateResponse.yaml @@ -3,3 +3,27 @@ content: application/json: schema: $ref: '../schemas/Buildpack.yaml' + examples: + default: + summary: default + value: + guid: fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + created_at: '2016-03-18T23:26:46Z' + updated_at: '2016-10-17T20:00:42Z' + name: ruby_buildpack + state: AWAITING_UPLOAD + filename: null + stack: windows64 + position: 42 + lifecycle: buildpack + enabled: true + locked: false + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + upload: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload + method: POST diff --git a/docs/openapi/apis/cf/latest/components/responses/BuildpackGetResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/BuildpackGetResponse.yaml index d9e0429acb6..f4cd00c1c58 100644 --- a/docs/openapi/apis/cf/latest/components/responses/BuildpackGetResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/BuildpackGetResponse.yaml @@ -3,3 +3,27 @@ content: application/json: schema: $ref: '../schemas/Buildpack.yaml' + examples: + default: + summary: default + value: + guid: fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + created_at: '2016-03-18T23:26:46Z' + updated_at: '2016-10-17T20:00:42Z' + name: ruby_buildpack + state: AWAITING_UPLOAD + filename: null + stack: windows64 + position: 42 + lifecycle: buildpack + enabled: true + locked: false + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + upload: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload + method: POST diff --git a/docs/openapi/apis/cf/latest/components/responses/DropletCreateResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/DropletCreateResponse.yaml index 01c18a6f127..c811bbd770a 100644 --- a/docs/openapi/apis/cf/latest/components/responses/DropletCreateResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/DropletCreateResponse.yaml @@ -1,5 +1,89 @@ -description: Successfully created droplet +description: Successfully created (or copied) droplet content: application/json: schema: $ref: '../schemas/Droplet.yaml' + examples: + default: + summary: default + value: + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 + state: AWAITING_UPLOAD + error: null + lifecycle: + type: buildpack + data: {} + execution_metadata: '' + process_types: + rake: bundle exec rake + web: bundle exec rackup config.ru -p $PORT + checksum: + type: sha256 + value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + buildpacks: + - name: ruby_buildpack + detect_output: ruby 1.6.14 + version: 1.1.1. + buildpack_name: ruby + stack: cflinuxfs4 + image: null + created_at: '2016-03-28T23:39:34Z' + updated_at: '2016-03-28T23:39:47Z' + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 + links: + self: + href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 + app: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 + assign_current_droplet: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet + method: PATCH + upload: + href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/upload + method: POST + metadata: + labels: {} + annotations: {} + copy: + summary: copy (with the source_guid query parameter) + value: + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 + state: COPYING + error: null + lifecycle: + type: buildpack + data: {} + execution_metadata: '' + process_types: null + checksum: null + buildpacks: null + stack: null + image: null + created_at: '2016-03-28T23:39:34Z' + updated_at: '2016-06-08T16:41:26Z' + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 + links: + self: + href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 + package: + href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 + app: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 + assign_current_droplet: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet + method: PATCH + metadata: + labels: {} + annotations: {} +links: + app: + operationId: getApp + parameters: + guid: $response.body#/relationships/app/data/guid + description: Retrieve the app for this droplet diff --git a/docs/openapi/apis/cf/latest/components/responses/DropletGetResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/DropletGetResponse.yaml index 7e74c30aa5b..f1dc98fb9f1 100644 --- a/docs/openapi/apis/cf/latest/components/responses/DropletGetResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/DropletGetResponse.yaml @@ -3,3 +3,54 @@ content: application/json: schema: $ref: '../schemas/Droplet.yaml' + examples: + default: + summary: default + value: + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 + state: STAGED + error: null + lifecycle: + type: buildpack + data: {} + execution_metadata: '' + process_types: + rake: bundle exec rake + web: bundle exec rackup config.ru -p $PORT + checksum: + type: sha256 + value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + buildpacks: + - name: ruby_buildpack + detect_output: ruby 1.6.14 + version: 1.1.1. + buildpack_name: ruby + stack: cflinuxfs4 + image: null + created_at: '2016-03-28T23:39:34Z' + updated_at: '2016-03-28T23:39:47Z' + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 + links: + self: + href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 + package: + href: https://api.example.org/v3/packages/8222f76a-9e09-4360-b3aa-1ed329945e92 + app: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 + assign_current_droplet: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet + method: PATCH + download: + href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download + metadata: + labels: {} + annotations: {} +links: + app: + operationId: getApp + parameters: + guid: $response.body#/relationships/app/data/guid + description: Retrieve the app for this droplet diff --git a/docs/openapi/apis/cf/latest/components/responses/RoleCreateResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/RoleCreateResponse.yaml index 8b501bfff54..2f4187d5f4f 100644 --- a/docs/openapi/apis/cf/latest/components/responses/RoleCreateResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/RoleCreateResponse.yaml @@ -3,3 +3,27 @@ content: application/json: schema: $ref: '../schemas/Role.yaml' + examples: + default: + summary: default + value: + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 + created_at: '2019-10-10T17:19:12Z' + updated_at: '2019-10-10T17:19:12Z' + type: organization_auditor + relationships: + user: + data: + guid: 59eadb5f-fc13-414f-84ba-77a35e239cc8 + organization: + data: + guid: 05c5da3b-6cbc-421c-87c3-20bb3c41ab7c + space: + data: null + links: + self: + href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 + user: + href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 + organization: + href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c diff --git a/docs/openapi/apis/cf/latest/components/responses/RoleGetResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/RoleGetResponse.yaml index f8332ea8b39..1c0eb72dbab 100644 --- a/docs/openapi/apis/cf/latest/components/responses/RoleGetResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/RoleGetResponse.yaml @@ -3,3 +3,27 @@ content: application/json: schema: $ref: '../schemas/Role.yaml' + examples: + default: + summary: default + value: + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 + created_at: '2019-10-10T17:19:12Z' + updated_at: '2019-10-10T17:19:12Z' + type: organization_auditor + relationships: + user: + data: + guid: 59eadb5f-fc13-414f-84ba-77a35e239cc8 + organization: + data: + guid: 05c5da3b-6cbc-421c-87c3-20bb3c41ab7c + space: + data: null + links: + self: + href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 + user: + href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 + organization: + href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c diff --git a/docs/openapi/apis/cf/latest/components/responses/RoleListResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/RoleListResponse.yaml index fb8b08329a6..8df6ab9905c 100644 --- a/docs/openapi/apis/cf/latest/components/responses/RoleListResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/RoleListResponse.yaml @@ -13,3 +13,58 @@ content: included: $ref: '../schemas/IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/roles?page=1&per_page=2 + last: + href: https://api.example.org/v3/roles?page=2&per_page=2 + next: + href: https://api.example.org/v3/roles?page=2&per_page=2 + previous: null + resources: + - guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 + created_at: '2019-10-10T17:19:12Z' + updated_at: '2019-10-10T17:19:12Z' + type: organization_auditor + relationships: + user: + data: + guid: 59eadb5f-fc13-414f-84ba-77a35e239cc8 + organization: + data: + guid: 05c5da3b-6cbc-421c-87c3-20bb3c41ab7c + space: + data: null + links: + self: + href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 + user: + href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 + organization: + href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c + - guid: 12347c70-d1bd-4976-a2ab-a85f5e882418 + created_at: '2047-11-10T17:19:12Z' + updated_at: '2047-11-10T17:19:12Z' + type: space_auditor + relationships: + user: + data: + guid: 47eadb5f-fc13-414f-84ba-47a35e239cc8 + organization: + data: null + space: + data: + guid: 47c5da3b-6cbc-421c-87c3-20bb3c41ab7c + links: + self: + href: https://api.example.org/v3/roles/12347c70-d1bd-4976-a2ab-a85f5e882418 + user: + href: https://api.example.org/v3/users/47eadb5f-fc13-414f-84ba-77a35e239cc8 + space: + href: https://api.example.org/v3/spaces/47c5da3b-6cbc-421c-87c3-20bb3c41ab7c diff --git a/docs/openapi/apis/cf/latest/components/responses/RouteCreateResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/RouteCreateResponse.yaml index bb487d61c17..5c281abd351 100644 --- a/docs/openapi/apis/cf/latest/components/responses/RouteCreateResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/RouteCreateResponse.yaml @@ -3,3 +3,50 @@ content: application/json: schema: $ref: '../schemas/Route.yaml' + examples: + default: + summary: default + value: + guid: cbad697f-cac1-48f4-9017-ac08f39dfb31 + protocol: tcp + port: 6666 + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + host: a-hostname + path: /some_path + url: a-hostname.a-domain.com/some_path + destinations: [] + options: + loadbalancing: round-robin + metadata: + labels: + key: value + annotations: + note: detailed information + relationships: + space: + data: + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + data: + guid: 0b5f3633-194c-42d2-9408-972366617e0e + links: + self: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 + space: + href: https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + href: https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e + destinations: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations +links: + space: + operationId: getSpace + parameters: + guid: $response.body#/relationships/space/data/guid + description: Retrieve the space for this route + domain: + operationId: getDomain + parameters: + guid: $response.body#/relationships/domain/data/guid + description: Retrieve the domain for this route diff --git a/docs/openapi/apis/cf/latest/components/responses/RouteListResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/RouteListResponse.yaml index e10f3bfa324..61d47e58f1d 100644 --- a/docs/openapi/apis/cf/latest/components/responses/RouteListResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/RouteListResponse.yaml @@ -2,11 +2,68 @@ description: A list of routes content: application/json: schema: - type: object - properties: - pagination: - $ref: '../schemas/Pagination.yaml' - resources: - type: array - items: - $ref: '../schemas/Route.yaml' + $ref: '../schemas/RouteList.yaml' + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/routes?page=1&per_page=2 + last: + href: https://api.example.org/v3/routes?page=2&per_page=2 + next: + href: https://api.example.org/v3/routes?page=2&per_page=2 + previous: null + resources: + - guid: cbad697f-cac1-48f4-9017-ac08f39dfb31 + protocol: http + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + host: a-hostname + path: /some_path + url: a-hostname.a-domain.com/some_path + destinations: + - guid: 385bf117-17f5-4689-8c5c-08c6cc821fed + app: + guid: 0a6636b5-7fc4-44d8-8752-0db3e40b35a5 + process: + type: web + weight: null + port: 8080 + protocol: http1 + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + - guid: 27e96a3b-5bcf-49ed-8048-351e0be23e6f + app: + guid: f61e59fa-2121-4217-8c7b-15bfd75baf25 + process: + type: web + weight: null + port: 8080 + protocol: http1 + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + options: + loadbalancing: round-robin + metadata: + labels: {} + annotations: {} + relationships: + space: + data: + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + data: + guid: 0b5f3633-194c-42d2-9408-972366617e0e + links: + self: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 + space: + href: https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + href: https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e + destinations: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations diff --git a/docs/openapi/apis/cf/latest/components/responses/UserCreateResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/UserCreateResponse.yaml index 42631fc3f47..7724646c884 100644 --- a/docs/openapi/apis/cf/latest/components/responses/UserCreateResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/UserCreateResponse.yaml @@ -3,3 +3,34 @@ content: application/json: schema: $ref: '../schemas/User.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' + username: some-name + presentation_name: some-name + origin: uaa + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + with_custom_origin: + summary: created by username and origin + value: + guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + username: some-user + presentation_name: some-user + origin: some-origin + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 diff --git a/docs/openapi/apis/cf/latest/components/responses/UserUpdateResponse.yaml b/docs/openapi/apis/cf/latest/components/responses/UserUpdateResponse.yaml index af106d691b4..2e7e6a84f97 100644 --- a/docs/openapi/apis/cf/latest/components/responses/UserUpdateResponse.yaml +++ b/docs/openapi/apis/cf/latest/components/responses/UserUpdateResponse.yaml @@ -3,3 +3,21 @@ content: application/json: schema: $ref: '../schemas/User.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' + username: some-name + presentation_name: some-name + origin: uaa + metadata: + labels: + environment: production + annotations: + note: detailed information + links: + self: + href: https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 diff --git a/docs/openapi/apis/cf/latest/components/schemas/App.yaml b/docs/openapi/apis/cf/latest/components/schemas/App.yaml index 7c37d6f6096..b3411520521 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/App.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/App.yaml @@ -2,24 +2,49 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the app + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated name: type: string - description: The name of the app + description: Name of the app state: type: string - description: Current desired state of the app + description: Current desired state of the app; valid values are `STOPPED` or `STARTED` 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 + 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](#builds) relationships: - $ref: './Relationships.yaml' + type: object + description: Relationships to other resources + properties: + space: + $ref: './RelationshipToOne.yaml' + description: The space the app is contained in + current_droplet: + $ref: './RelationshipToOne.yaml' + description: The current droplet used by the application metadata: $ref: './Metadata.yaml' + description: |- + `labels`: Labels applied to the app + + `annotations`: Annotations added to the app links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' @@ -64,4 +89,4 @@ allOf: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter 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. + Apps are top-level objects that link together and contain configuration information for your packages, droplets, processes, tasks, and more. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppCredentialBinding.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppCredentialBinding.yaml index ed97907dd43..148554e83f2 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppCredentialBinding.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppCredentialBinding.yaml @@ -6,39 +6,53 @@ allOf: type: string enum: - app - description: Type of credential binding + description: Either `app` or `key` name: type: [string, "null"] - description: Name of the credential binding + description: Name of the binding. `null` when it's not defined. last_operation: $ref: './ServiceCredentialBindingLastOperation.yaml' + description: The last operation of this binding relationships: type: object properties: app: $ref: './RelationshipToOne.yaml' + description: The app using this binding; omitted for `key` bindings service_instance: $ref: './RelationshipToOne.yaml' - description: Relationships for the credential binding + description: The service instance that this binding is originated from + description: Relationships for the service credential binding links: type: object properties: self: $ref: './Link.yaml' + description: Link to this service credential binding details: $ref: './Link.yaml' + description: Link to the details of this service credential binding app: $ref: './Link.yaml' + description: Link to the app using this binding service_instance: $ref: './Link.yaml' + description: Link to the service instance that this binding is originated from parameters: $ref: './Link.yaml' + description: Link to the parameters that this binding was created with; only present for bindings to managed service instances + description: Links to related resources metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service credential binding included: $ref: './IncludedResources.yaml' - description: Additional related resources included in the response when using the include parameter + description: Additional related resources included in the response when using the `include` parameter required: - - type - - relationships - - links \ No newline at end of file + - type + - relationships + - links +description: |- + A service credential binding of type `app`; a binding between a [service instance](#service-instances) and an + [application](#apps). Not all services support this binding, as some services deliver value to users directly + without integration with an application. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppEnvironment.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppEnvironment.yaml index 5263ee5b14b..36967e690cc 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppEnvironment.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppEnvironment.yaml @@ -2,23 +2,25 @@ type: object properties: staging_env_json: type: object - description: Environment variables used during staging + description: Environment variables from the staging environment variable group, provided to the app during staging additionalProperties: true running_env_json: type: object - description: Environment variables used during runtime + description: Environment variables from the running environment variable group, provided to the app at runtime additionalProperties: true environment_variables: type: object - description: User-defined environment variables + description: Environment variables that are associated with the given app additionalProperties: type: [string, "null"] system_env_json: type: object - description: System environment variables including VCAP_SERVICES + description: System-provided environment variables, including `VCAP_SERVICES`; redacted for Space Supporters additionalProperties: true application_env_json: type: object - description: Application environment variables including VCAP_APPLICATION + description: Application-provided environment variables, including `VCAP_APPLICATION` additionalProperties: true -description: 'Environment variables that will be provided to an app at runtime' +description: |- + The environment variables that will be provided to an app at runtime. + It will include environment variables for Environment Variable Groups and Service Bindings. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppEnvironmentVariables.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppEnvironmentVariables.yaml index 97f3dbedd80..e3217866fa9 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppEnvironmentVariables.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppEnvironmentVariables.yaml @@ -2,11 +2,12 @@ type: object properties: var: type: object - description: Environment variables + description: Environment variables that are associated with the given app; keys and values are strings additionalProperties: type: [string, "null"] links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' @@ -14,4 +15,4 @@ properties: app: $ref: './Link.yaml' description: The URL to get the app for these environment variables -description: 'App environment variables with links' +description: The environment variables that are associated with the given app diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppFeature.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppFeature.yaml index 4c7a1f5f7f7..d05a6a827e0 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppFeature.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppFeature.yaml @@ -2,12 +2,19 @@ type: object properties: name: type: string - description: The name of the app feature + description: Name of the app feature + enum: + - ssh + - revisions + - service-binding-k8s + - file-based-vcap-services description: type: [string, "null"] - description: The description of the app feature + description: Description of the app feature enabled: type: boolean description: Denotes whether or not the app feature is enabled -description: > +description: |- App features are used to manage whether optional capabilities are enabled for a given application. + See the App Features section for the list of supported features and for how service binding files are + derived from `VCAP_SERVICES`. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppFeatureList.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppFeatureList.yaml index c796e2931a3..bf8e56887cd 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppFeatureList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppFeatureList.yaml @@ -1,8 +1,11 @@ type: object properties: pagination: - $ref: '#/components/schemas/Pagination' + $ref: './Pagination.yaml' + description: Pagination information for the list of app features resources: type: array items: - $ref: '#/components/schemas/AppFeature' + $ref: './AppFeature.yaml' + description: List of app features +description: A list of the features available for an app diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppList.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppList.yaml index dcd3ea84ab8..3e6e5277255 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppList.yaml @@ -2,10 +2,13 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of apps resources: type: array items: $ref: './App.yaml' + description: List of apps included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter +description: A paginated list of apps diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppPermissions.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppPermissions.yaml index b89ddd0e925..e65bb1a704f 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppPermissions.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppPermissions.yaml @@ -2,11 +2,11 @@ type: object properties: read_basic_data: type: boolean - description: Whether the user can read basic app data + description: Whether the current user can read the app's basic data; true if the user can see the app read_sensitive_data: type: boolean - description: Whether the user can read sensitive app data + description: Whether the current user can read the app's sensitive data; only admin, read-only admins, and space developers can read sensitive data required: - read_basic_data - read_sensitive_data -description: 'User permissions for an app' +description: The current user's permissions for the given app diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppSshEnabled.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppSshEnabled.yaml index 273806515b9..211e45e998d 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppSshEnabled.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppSshEnabled.yaml @@ -2,10 +2,14 @@ type: object properties: enabled: type: boolean - description: Whether SSH is enabled for the app + description: Denotes whether the application's runtime environment will accept ssh connections reason: type: string - description: If SSH is disabled, describes whether it is disabled globally, at the space level, or at the app level + description: If ssh is disabled, describes whether it is disabled globally, at the space level, or at the app level required: - enabled -description: 'SSH enabled status for an app' +description: |- + Whether an application's runtime environment will accept ssh connections. + If ssh is disabled, + the `reason` field will describe + whether it is disabled globally, at the space level, or at the app level. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppUsageEvent.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppUsageEvent.yaml index 5cf0cb50fe2..bd7eeabada8 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppUsageEvent.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppUsageEvent.yaml @@ -1,86 +1,114 @@ type: object allOf: - $ref: './BaseSchema.yaml' -properties: - state: - type: object - properties: - current: - type: string - description: Current state of the app that this event pertains to, if applicable - previous: - type: [string, "null"] - description: Previous state of the app that this event pertains to, if applicable - app: - type: object - properties: - guid: - type: string - description: Unique identifier of the app that this event pertains to, if applicable - name: - type: [string, "null"] - description: Name of the app that this event pertains to, if applicable - process: - type: object - properties: - guid: - type: string - description: Unique identifier of the process that this event pertains to, if applicable - type: - type: string - description: Type of the process that this event pertains to, if applicable - space: - type: object - properties: + - properties: guid: type: string - description: Unique identifier of the space that this event pertains to, if applicable - name: - type: [string, "null"] - description: Name of the space that this event pertains to, if applicable - organization: - type: object - properties: - guid: + format: uuid + description: Unique identifier for the event + created_at: type: string - description: Unique identifier of the org that this event pertains to, if applicable - buildpack: - type: object - properties: - guid: - type: string - description: Unique identifier of the buildpack that this event pertains to, if applicable - name: - type: [string, "null"] - description: Name of the buildpack that this event pertains to, if applicable - task: - type: object - properties: - guid: + format: date-time + description: The time with zone when the event occurred + updated_at: type: string - description: Unique identifier of the task that this event pertains to, if applicable - name: - type: [string, "null"] - description: Name of the task that this event pertains to, if applicable - memory_in_mb_per_instance: - type: object - properties: - current: - type: integer - description: Current memory in MB of the app that this event pertains to, if applicable - previous: - type: [integer, "null"] - description: Previous memory in MB of the app that this event pertains to, if applicable - instance_count: - type: object - properties: - current: - type: integer - description: Current instance count of the app that this event pertains to, if applicable - previous: - type: [integer, "null"] - description: Previous instance count of the app that this event pertains to, if applicable -description: >- + format: date-time + description: Identical to `created_at` (events are created, never updated) + state: + type: object + description: The state of the app that this event pertains to + properties: + current: + type: [string, "null"] + description: Current state of the app that this event pertains to, if applicable + previous: + type: [string, "null"] + description: Previous state of the app that this event pertains to, if applicable + app: + type: object + description: The app that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the app that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the app that this event pertains to, if applicable + process: + type: object + description: The process that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the process that this event pertains to, if applicable + type: + type: [string, "null"] + description: Type of the process that this event pertains to, if applicable + space: + type: object + description: The space that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the space that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the space that this event pertains to, if applicable + organization: + type: object + description: The organization that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the org that this event pertains to, if applicable + buildpack: + type: object + description: The buildpack that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the buildpack that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the buildpack that this event pertains to, if applicable + task: + type: object + description: The task that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the task that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the task that this event pertains to, if applicable + memory_in_mb_per_instance: + type: object + description: The memory per instance of the app that this event pertains to + properties: + current: + type: [integer, "null"] + description: Current memory in MB of the app that this event pertains to, if applicable + previous: + type: [integer, "null"] + description: Previous memory in MB of the app that this event pertains to, if applicable + instance_count: + type: object + description: The instance count of the app that this event pertains to + properties: + current: + type: [integer, "null"] + description: Current instance count of the app that this event pertains to, if applicable + previous: + type: [integer, "null"] + description: Previous instance count of the app that this event pertains to, if applicable + links: + type: object + description: Links to related resources + properties: + self: + $ref: './Link.yaml' + description: The URL to get this app usage event +description: |- App usage events are a record of changes in the usage of apps and tasks. Examples include starting an application, scaling an application (from, say, one to three instances), and stopping an application. Usage events are typically used by billing and chargeback applications. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AppUsageEventList.yaml b/docs/openapi/apis/cf/latest/components/schemas/AppUsageEventList.yaml index 21fc8223ba2..2846b471325 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AppUsageEventList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AppUsageEventList.yaml @@ -2,7 +2,9 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of app usage events resources: type: array items: $ref: './AppUsageEvent.yaml' + description: The list of app usage events diff --git a/docs/openapi/apis/cf/latest/components/schemas/AuditEvent.yaml b/docs/openapi/apis/cf/latest/components/schemas/AuditEvent.yaml index 1a11b1bf692..5750b40aa39 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AuditEvent.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AuditEvent.yaml @@ -2,15 +2,28 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the event + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated type: type: string - description: The type of the event + description: The type of the event; see the "Audit Event Types" list in the Audit Events resource description for the full set of values actor: type: object + description: The user or system resource that performed the action properties: guid: type: string - description: The unique identifier for the actor (user or system resource that performed the action) + description: Unique identifier for the actor (user or system resource that performed the action) type: type: string description: The actor type @@ -19,10 +32,12 @@ allOf: description: The name of the actor target: type: object + description: The resource that the event acted upon properties: guid: type: string - description: The unique identifier for the target (resource that the event acted upon) + format: uuid + description: Unique identifier for the target (resource that the event acted upon) type: type: string description: The target type @@ -31,24 +46,30 @@ allOf: description: The name of the target data: type: object + additionalProperties: true description: Additional information about event space: type: [object, "null"] + description: The space where the event occurred; if the event did not occur within a space, the `space` field will be `null` properties: guid: type: string + format: uuid description: Unique identifier for the space where the event occurred; if the event did not occur within a space, the `space` field will be `null` organization: type: [object, "null"] + description: The organization where the event occurred; if the event did not occur within an organization, the `organization` field will be `null` properties: guid: type: string + format: uuid description: Unique identifier for the organization where the event occurred; if the event did not occur within an organization, the `organization` field will be `null` links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' description: The URL to get this audit event -description: > +description: |- Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions. diff --git a/docs/openapi/apis/cf/latest/components/schemas/AuditEventList.yaml b/docs/openapi/apis/cf/latest/components/schemas/AuditEventList.yaml index 9cb07ea86b8..728d5a135f7 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/AuditEventList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/AuditEventList.yaml @@ -2,7 +2,9 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of audit events resources: type: array items: $ref: './AuditEvent.yaml' + description: The list of audit events diff --git a/docs/openapi/apis/cf/latest/components/schemas/Build.yaml b/docs/openapi/apis/cf/latest/components/schemas/Build.yaml index 1f0286c2f0f..d0bb6aabdcd 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Build.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Build.yaml @@ -2,9 +2,21 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the build + created_at: + type: string + format: date-time + description: The time with zone when the build was created + updated_at: + type: string + format: date-time + description: The time with zone when the build was last updated state: type: string - description: State of the build + description: State of the build; valid states are `STAGING`, `STAGED`, or `FAILED` enum: - STAGING - STAGED @@ -16,43 +28,33 @@ allOf: type: [integer, "null"] description: Disk space in MB allocated for staging of the build staging_log_rate_limit_bytes_per_second: - type: integer + type: [integer, "null"] description: Log rate limit in bytes per second allocated for staging of the build error: type: [string, 'null'] description: A string describing errors during the build process lifecycle: $ref: './Lifecycle.yaml' - description: Provides the lifecycle object to use during staging; this will override the build’s application’s default lifecycle for this build - checksum: - type: object - properties: - type: - type: string - description: Hashing algorithm for checksum; supported algorithms are sha256 and sha1 - value: - type: string - description: Checksum of build - metadata: - $ref: './Metadata.yaml' - relationships: - $ref: './Relationships.yaml' + description: Provides the lifecycle object to use during staging; this will override the build's application's default lifecycle for this build package: type: object + description: The package that is the input to the staging process properties: guid: type: string format: uuid - description: The package that is the input to the staging process + description: The guid of the package that is the input to the staging process droplet: type: [object, 'null'] + description: A resulting droplet from the staging process; `droplet` will be `null` if staging has not completed properties: guid: type: string format: uuid - description: A resulting droplet from the staging process; `droplet` will be `null` if staging has not completed + description: The guid of the droplet resulting from the staging process created_by: type: object + description: The user that created the build properties: guid: type: string @@ -63,8 +65,22 @@ allOf: email: type: [string, "null"] description: The email of the user that created the build + relationships: + type: object + description: Relationships to other resources + properties: + app: + $ref: './RelationshipToOne.yaml' + description: The app the build belongs to + metadata: + $ref: './Metadata.yaml' + description: |- + `labels`: Labels applied to the build + + `annotations`: Annotations applied to the build links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' @@ -74,6 +90,8 @@ allOf: description: The URL to get the app for this build droplet: $ref: './Link.yaml' - description: The URL to get the droplet for this build -description: > - Builds represent the process of transforming source code into a runnable artifact. Builds can be triggered manually or automatically as part of the app lifecycle. A successful build results in a droplet that can be used to run the app. + description: The URL to get the droplet resulting from this build; only present once staging has completed +description: |- + Builds represent the process of staging an application package. There are two types ([lifecycles](#lifecycles)) of builds: buildpack and docker. + + After an [application](#apps) is created and [packages](#packages) are uploaded, a build resource can be created to initiate the staging process. A successful build results in a [droplet](#droplets). diff --git a/docs/openapi/apis/cf/latest/components/schemas/BuildList.yaml b/docs/openapi/apis/cf/latest/components/schemas/BuildList.yaml index 3c9782836ad..ed6ba739d31 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/BuildList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/BuildList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of builds resources: type: array + description: The list of builds items: $ref: './Build.yaml' +description: A paginated list of builds diff --git a/docs/openapi/apis/cf/latest/components/schemas/BuildUpdate.yaml b/docs/openapi/apis/cf/latest/components/schemas/BuildUpdate.yaml index d1f736fc9f3..af512620fd1 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/BuildUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/BuildUpdate.yaml @@ -2,25 +2,33 @@ type: object properties: state: type: string - description: State of the build + description: Build status; valid values are `FAILED` or `STAGED` (field can only be passed by Build State Updaters) enum: - - STAGING - STAGED - FAILED - staging_memory_in_mb: - type: [integer, "null"] - description: Memory in MB allocated for staging of the build - staging_disk_in_mb: - type: [integer, "null"] - description: Disk space in MB allocated for staging of the build - staging_log_rate_limit_bytes_per_second: - type: integer - description: Log rate limit in bytes per second allocated for staging of the build error: type: [string, 'null'] - description: A string describing errors during the build process + description: A string describing errors during the build process (field can only be passed by Build State Updaters) lifecycle: - $ref: './Lifecycle.yaml' - description: Provides the lifecycle object to use during staging + type: object + description: Lifecycle information for the build (field can only be passed by Build State Updaters) + properties: + type: + type: string + description: Type of the lifecycle; valid values are `buildpack`, `cnb`, `docker` + data: + type: object + description: Data specific to the lifecycle + properties: + image: + type: string + description: Image reference tag where the built complete image was stored (field can only be passed by Build State Updaters) + processTypes: + type: object + additionalProperties: + type: string + description: Process types detected during staging, keyed by process type (field can only be passed by Build State Updaters) metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the build +description: Request schema for updating a build diff --git a/docs/openapi/apis/cf/latest/components/schemas/Buildpack.yaml b/docs/openapi/apis/cf/latest/components/schemas/Buildpack.yaml index e53679c5a31..e7d5673a224 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Buildpack.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Buildpack.yaml @@ -2,12 +2,24 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the buildpack + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated name: type: string description: The name of the buildpack; to be used by app buildpack field (only alphanumeric characters) state: type: string - description: The state of the buildpack + description: 'The state of the buildpack; valid states are: `AWAITING_UPLOAD`, `READY`' enum: - AWAITING_UPLOAD - READY @@ -17,6 +29,12 @@ allOf: lifecycle: type: string description: The version of buildpacks the buildpack uses. `buildpack` indicates [Classic Buildpacks](https://docs.cloudfoundry.org/buildpacks/classic.html). `cnb` indicates [Cloud Native Buildpacks](https://docs.cloudfoundry.org/buildpacks/cnb/) + enum: + - buildpack + - cnb + filename: + type: [string, 'null'] + description: The filename of the buildpack position: type: integer description: The order in which the buildpacks are checked during buildpack auto-detection @@ -26,18 +44,23 @@ allOf: locked: type: boolean description: Whether or not the buildpack is locked to prevent updating the bits - filename: - type: [string, 'null'] - description: The filename of the buildpack metadata: $ref: './Metadata.yaml' + description: |- + `labels`: Labels applied to the app + + `annotations`: Annotations added to the app links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL of the buildpack + description: The URL to get this buildpack upload: $ref: './Link.yaml' - description: The URL to upload the buildpack -description: A buildpack represents a set of scripts used to prepare an application for launch. + description: The URL to upload the bits for this buildpack +description: |- + Buildpacks are used during a [build](#builds) to download external dependencies and transform a [package](#packages) into an executable [droplet](#droplets). In this way, buildpacks are a pluggable extension to Cloud Foundry that enable CF to run different languages and frameworks. + + Buildpacks will automatically detect if they support an application. Buildpacks can also be explicitly specified on [apps](#apps) and [builds](#builds). diff --git a/docs/openapi/apis/cf/latest/components/schemas/BuildpackList.yaml b/docs/openapi/apis/cf/latest/components/schemas/BuildpackList.yaml index 6ef12f99868..de8fd37bab2 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/BuildpackList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/BuildpackList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of buildpacks resources: type: array + description: The list of buildpacks items: $ref: './Buildpack.yaml' +description: A paginated list of buildpacks diff --git a/docs/openapi/apis/cf/latest/components/schemas/Deployment.yaml b/docs/openapi/apis/cf/latest/components/schemas/Deployment.yaml index ce00d593125..0e58fa8beca 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Deployment.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Deployment.yaml @@ -2,18 +2,41 @@ type: object allOf: - $ref: ./BaseSchema.yaml - properties: + guid: + type: string + format: uuid + description: Unique identifier for the deployment + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated status: type: object + description: The status of the deployment properties: value: type: string - description: The current status of the deployment + description: The current status of the deployment; valid values are `ACTIVE` (meaning in progress) and `FINALIZED` (meaning finished, either successfully or not) enum: - ACTIVE - FINALIZED reason: type: string - description: The reason for the status of the deployment + description: |- + The reason for the status of the deployment; + following list represents valid values: + 1. If **status.value** is `ACTIVE` + - `DEPLOYING` + - `PAUSED` (only valid for canary deployments) + - `CANCELING` + 2. If **status.value** is `FINALIZED` + - `DEPLOYED` + - `CANCELED` + - `SUPERSEDED` (another deployment created for app before completion) enum: - DEPLOYING - PAUSED @@ -23,105 +46,154 @@ allOf: - SUPERSEDED details: type: object + description: Additional detail about the current status of the deployment properties: last_successful_healthcheck: type: string format: date-time - description: Timestamp of the last successful health check + description: Timestamp of the last successful healthcheck last_status_change: type: string format: date-time description: Timestamp of last change to status.value or status.reason + error: + type: [string, "null"] + description: Brief description of error encountered while deploying, if any. This field is cleared once the deployment progresses successfully. + canary: + type: object + description: Canary status of the deployment. Only available for deployments with strategy 'canary'. (experimental) + properties: + steps: + type: object + description: Progress through the configured canary steps. Only available for deployments with strategy 'canary'. (experimental) + properties: + current: + type: integer + description: The current canary step. Only available for deployments with strategy 'canary'. (experimental) + total: + type: integer + description: The total number of canary steps. Only available for deployments with strategy 'canary'. (experimental) strategy: type: string - description: Strategy used for the deployment + description: Strategy used for the deployment; supported strategies are `rolling` and `canary` (experimental) enum: - rolling - canary options: type: object + description: Options that were used for the deployment properties: 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 + description: The number of web instances the deployment will scale to memory_in_mb: - type: integer - description: The amount of memory in megabytes to allocate for the web process + type: [integer, "null"] + description: The amount of memory in megabytes to allocate per web process instance. If `null`, the amount allocated will be taken from the previous web process. disk_in_mb: - type: integer - description: The amount of disk space in megabytes to allocate for the web process + type: [integer, "null"] + description: The amount of disk in megabytes to allocate per web process instance. If `null`, the amount allocated will be taken from the previous 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. + type: [integer, "null"] + description: Log rate limit in bytes per second to allocate per web process instance. If `null`, the amount allocated will be taken from the previous web process. canary: type: object - description: Configuration for canary deployments. Present when strategy is 'canary'. + description: Canary options used for the deployment. Only available for deployments with strategy 'canary'. (experimental) properties: steps: type: array - description: Array of steps defining the canary deployment progression + description: Canary steps to use for the deployment. Only available for deployments with strategy 'canary'. (experimental) items: type: object + description: A canary step object properties: instance_weight: type: integer - description: The percentage of instances to be deployed as part of the canary process in this step + description: The percentage of instances to be deployed as part of the canary process in this step (experimental) droplet: type: object + description: The droplet the deployment is transitioning the app to properties: guid: type: string format: uuid - description: The droplet guid that the deployment is transitioning the app to + description: The droplet guid that the deployment is transitioning the app to previous_droplet: type: object + description: The app's droplet before the deployment was created properties: guid: type: string format: uuid - description: "The app\u2019s [current droplet guid](#get-current-droplet-association-for-an-app) before the deployment was created" + description: The app's [current droplet guid](#get-current-droplet-association-for-an-app) before the deployment was created new_processes: type: array + description: List of processes created as part of the deployment items: type: object properties: guid: type: string format: uuid - description: The GUID of the new process created as part of the deployment + description: The GUID of the process created as part of the deployment type: type: string - description: The type of the new process created as part of the deployment + description: The type of the process created as part of the deployment revision: type: [object, "null"] + description: The [revision](#revisions) the deployment is transitioning the app to properties: guid: type: string format: uuid - description: The revision the deployment is transitioning the app to + description: The GUID of the revision the deployment is transitioning the app to version: type: integer - description: The version of the revision + description: Human-readable identifier for the revision relationships: - $ref: ./Relationships.yaml + type: object + description: Relationships to other resources + properties: + app: + $ref: ./RelationshipToOne.yaml + description: The app the deployment is updating metadata: $ref: ./Metadata.yaml + description: |- + `labels`: Labels applied to the deployment + + `annotations`: Annotations applied to the deployment links: type: object + description: Links to related resources properties: self: $ref: ./Link.yaml description: The URL to get this deployment app: $ref: ./Link.yaml - description: The URL to get the app for this deployment + description: The URL to get the app the deployment is updating cancel: $ref: ./Link.yaml - description: The URL to cancel this deployment + description: The URL to cancel this deployment; only present while the deployment can be canceled continue: $ref: ./Link.yaml - description: The URL to continue this deployment -description: "Deployments are objects that manage updates to applications with zero downtime. They can either: - Manage updating an app\u2019s droplet directly after an application package is staged - Roll an app back to a specific revision along with its associated droplet\nDeployment strategies supported: - Rolling deployments allow for applications to be deployed without incurring downtime by gradually rolling out instances. Max-in-flight can be configured to specify how many instances are rolled out simultaneously. - Canary deployments deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via the continue action. The deployment then continues like a rolling deployment. This feature is experimental and is subject to change.\n" + description: The URL to continue this deployment; only present while the deployment is paused and can be continued +description: |- + Deployments are objects that manage updates to applications with zero downtime. + + They can either: + + * Manage updating an app's [droplet](#droplets) directly after an application package is staged + + * Roll an app back to a specific [revision](#revisions) along with its associated droplet + + Deployments are different than the traditional method of pushing app updates which performs start/stop deployments. + + Deployment strategies supported: + + * [Rolling deployments](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html) allows for applications to be deployed without incurring downtime by gradually rolling out instances. Max-in-flight can be configured to specify how many instances are rolled out simultaneously. + + * [Canary deployments](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html#canary-deployment-process) deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via the [continue action](#continue-a-deployment). The deployment then continues like a rolling deployment. This feature is experimental and is subject to change. diff --git a/docs/openapi/apis/cf/latest/components/schemas/DeploymentList.yaml b/docs/openapi/apis/cf/latest/components/schemas/DeploymentList.yaml index 3b582fd2cf3..63d4106cfba 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/DeploymentList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/DeploymentList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of deployments resources: type: array items: $ref: './Deployment.yaml' + description: List of deployments +description: A paginated list of deployments 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/Droplet.yaml b/docs/openapi/apis/cf/latest/components/schemas/Droplet.yaml index 81fc21a99af..63ab0687371 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Droplet.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Droplet.yaml @@ -4,54 +4,79 @@ allOf: - properties: state: type: string - description: State of the droplet; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, STAGED, COPYING, FAILED, or EXPIRED + description: State of the droplet; valid states are `AWAITING_UPLOAD`, `PROCESSING_UPLOAD`, `STAGED`, `COPYING`, `FAILED`, or `EXPIRED` + enum: + - AWAITING_UPLOAD + - PROCESSING_UPLOAD + - STAGED + - COPYING + - FAILED + - EXPIRED error: type: [string, 'null'] description: A string describing the last error during the droplet lifecycle lifecycle: $ref: './Lifecycle.yaml' + description: An object describing the lifecycle that was used when staging the droplet; `lifecycle.data` will always be an empty hash for lifecycles of type `docker` execution_metadata: type: [string, "null"] description: Serialized JSON data resulting from staging for use when executing a droplet process_types: - type: object + type: [object, "null"] + additionalProperties: + type: string description: The process types (keys) and associated start commands (values) that will be created when the droplet is executed + relationships: + type: object + description: The relationships of the droplet + properties: + app: + $ref: './RelationshipToOne.yaml' + description: The app the droplet belongs to metadata: $ref: './Metadata.yaml' + description: Labels and annotations on the droplet links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' description: The URL to get this droplet package: $ref: './Link.yaml' - description: The URL to get the package for this droplet + description: The URL to get the package the droplet was staged from app: $ref: './Link.yaml' - description: The URL to get the app for this droplet + description: The URL to get the app the droplet belongs to assign_current_droplet: $ref: './Link.yaml' - description: The URL to assign the droplet to an application + description: The URL to assign this droplet as the current droplet of its app download: $ref: './Link.yaml' - description: The URL to download the droplet + description: The URL to download the droplet bits; present only for droplets in the `STAGED` state with lifecycle type `buildpack` upload: $ref: './Link.yaml' - description: The URL to upload the droplet + description: The URL to upload the droplet bits; present only for droplets in the `AWAITING_UPLOAD` state checksum: type: [object, 'null'] + description: Checksum of the droplet bits; only present on droplets with lifecycle type `buildpack` properties: type: type: string - description: Hashing algorithm for checksum; supported algorithms are sha256 and sha1 + description: Hashing algorithm for checksum; supported algorithms are `sha256` and `sha1` + enum: + - sha256 + - sha1 value: type: string - description: Checksum of the droplet + description: Checksum of droplet buildpacks: type: [array, "null"] + description: Detected buildpacks from the staging process; only present on droplets with lifecycle type `buildpack` items: type: object + description: A detected buildpack object properties: name: type: [string, "null"] @@ -59,16 +84,19 @@ allOf: detect_output: type: [string, 'null'] description: Output during buildpack detect process - version: - type: [string, 'null'] - description: Version reported by the buildpack buildpack_name: type: [string, "null"] description: Name reported by the buildpack + version: + type: [string, 'null'] + description: Version reported by the buildpack stack: type: [string, 'null'] - description: The root filesystem to use with the buildpack, for example cflinuxfs4 + description: The root filesystem to use with the buildpack, for example `cflinuxfs4`; only present on droplets with lifecycle type `buildpack` image: type: [string, 'null'] - description: Docker image name for Docker droplets -description: A droplet is the result of staging an application package. There are two types (lifecycles) of droplets buildpack and docker. In the case of the buildpacks, the droplet contains the bits produced by the buildpack, typically application code and dependencies. + description: Docker image name; only present on droplets with lifecycle type `docker` +description: |- + Droplets are the result of staging an application package. There are two types (lifecycles) of droplets: buildpack and docker. In the case of the buildpacks, the droplet contains the bits produced by the buildpack, typically application code and dependencies. + + In addition to the common fields, a droplet object contains the fields from both lifecycles. Their values are `null` by default and contain values when the droplet is of a specific `lifecycle.type`. Buildpack droplets carry `checksum`, `buildpacks`, and `stack`; Docker droplets carry `image`. diff --git a/docs/openapi/apis/cf/latest/components/schemas/DropletList.yaml b/docs/openapi/apis/cf/latest/components/schemas/DropletList.yaml index 5966da8cfa3..f20ec136d89 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/DropletList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/DropletList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of droplets resources: type: array + description: The list of droplets items: $ref: './Droplet.yaml' +description: A paginated list of droplets diff --git a/docs/openapi/apis/cf/latest/components/schemas/EnvironmentVariableGroup.yaml b/docs/openapi/apis/cf/latest/components/schemas/EnvironmentVariableGroup.yaml index 46af31a2f80..4ff23b0ff2a 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/EnvironmentVariableGroup.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/EnvironmentVariableGroup.yaml @@ -3,17 +3,21 @@ properties: updated_at: type: string format: date-time - description: The time the environment variable group was last updated + description: The time of last update name: - type: [string, "null"] - description: The name of the group; can only be "running" or "staging" + type: string + enum: + - running + - staging + description: The name of the group; can only be `running` or `staging` var: type: object additionalProperties: - type: [string, "null"] + type: string description: Environment variables to inject; keys and values must be strings links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' diff --git a/docs/openapi/apis/cf/latest/components/schemas/FeatureFlag.yaml b/docs/openapi/apis/cf/latest/components/schemas/FeatureFlag.yaml index 72bc762bc0c..4100386082c 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/FeatureFlag.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/FeatureFlag.yaml @@ -9,12 +9,13 @@ properties: updated_at: type: [string, "null"] format: date-time - description: The time the feature flag was last updated; this will be blank for feature flags that have not been configured + description: The time with zone when the object was last updated; this will be blank for feature flags that have not been configured custom_error_message: type: [string, "null"] description: The error string returned by the API when a client performs an action disabled by the feature flag links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' diff --git a/docs/openapi/apis/cf/latest/components/schemas/FeatureFlagList.yaml b/docs/openapi/apis/cf/latest/components/schemas/FeatureFlagList.yaml index 3ab81a30d3c..f3b946b4127 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/FeatureFlagList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/FeatureFlagList.yaml @@ -1,8 +1,13 @@ type: object properties: pagination: - $ref: './Pagination.yaml' + allOf: + - $ref: './Pagination.yaml' + - description: Pagination information for the list of feature flags resources: type: array + description: A list of feature flags items: $ref: './FeatureFlag.yaml' +description: > + A paginated list of feature flags. diff --git a/docs/openapi/apis/cf/latest/components/schemas/HealthCheck.yaml b/docs/openapi/apis/cf/latest/components/schemas/HealthCheck.yaml index fc62fc5098d..3b56be6c535 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/HealthCheck.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/HealthCheck.yaml @@ -2,21 +2,23 @@ type: object properties: type: type: string - enum: ["port", "process", "http"] - description: The type of health check to perform; valid values are http, port, and process; default is port + enum: ["http", "port", "process"] + default: port + description: The type of health check to perform; valid values are `http`, `port`, and `process`; default is `port` data: type: object + description: Configuration for the health check properties: timeout: type: [integer, 'null'] description: The duration in seconds that health checks can fail before the process is restarted invocation_timeout: type: [integer, 'null'] - description: The timeout in seconds for individual health check requests for http and port health checks + description: The timeout in seconds for individual health check requests for `http` and `port` health checks interval: type: [integer, 'null'] description: The interval in seconds between health check requests endpoint: - type: string - description: The endpoint called to determine if the app is healthy; this key is only present for http health checks -description: 'Health check configuration for a process' + type: [string, 'null'] + description: The endpoint called to determine if the app is healthy; this key is only present for `http` health checks +description: 'The health check to perform on the process' diff --git a/docs/openapi/apis/cf/latest/components/schemas/IncludedResources.yaml b/docs/openapi/apis/cf/latest/components/schemas/IncludedResources.yaml index a2d3158d5eb..9b56fba5ad1 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/IncludedResources.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/IncludedResources.yaml @@ -48,4 +48,19 @@ properties: items: $ref: './User.yaml' description: Array of included user resources + route_policies: + type: array + items: + $ref: './RoutePolicy.yaml' + description: Array of included route policy resources + service_plans: + type: array + items: + $ref: './ServicePlan.yaml' + description: Array of included service plan resources + service_brokers: + type: array + items: + $ref: './ServiceBroker.yaml' + description: Array of included service broker resources additionalProperties: false diff --git a/docs/openapi/apis/cf/latest/components/schemas/Info.yaml b/docs/openapi/apis/cf/latest/components/schemas/Info.yaml new file mode 100644 index 00000000000..f8d9b7d974b --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/Info.yaml @@ -0,0 +1,58 @@ +type: object +properties: + build: + type: string + description: The Cloud Controller build number, as configured by the platform operator; blank when it is not configured + cli_version: + type: object + description: Minimum and recommended versions of the Cloud Foundry CLI for use with this API + properties: + minimum: + type: string + description: Minimum version of the CF CLI to work with the API; blank when it is not configured + recommended: + type: string + description: Minimum recommended version of the CF CLI; blank when it is not configured + custom: + type: object + additionalProperties: true + description: Custom attribute keys and values configured by the platform operator; empty when none are configured + description: + type: string + description: A description of the platform, as configured by the platform operator; blank when it is not configured + name: + type: string + description: The name of the platform, as configured by the platform operator; blank when it is not configured + version: + type: integer + description: The version of the platform, as configured by the platform operator; `0` when it is not configured + osbapi_version: + type: string + description: The version of the Open Service Broker API supported by this platform; blank when it cannot be determined + rate_limits: + type: object + description: The request rate limits applied to UAA-authenticated endpoints + properties: + enabled: + type: boolean + description: Whether rate limiting is enabled for UAA-authenticated endpoints per user or client + general_limit: + type: integer + 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 + reset_interval_in_minutes: + type: integer + description: The interval in minutes after which a user's available API requests will be reset + links: + type: object + description: Links to related resources + properties: + self: + allOf: + - $ref: './Link.yaml' + - description: Link to the current endpoint + support: + allOf: + - $ref: './Link.yaml' + - description: Link to the support address for the platform; blank when it is not configured +description: |- + Descriptive information about the Cloud Controller and the platform it is running on. diff --git a/docs/openapi/apis/cf/latest/components/schemas/InfoUsageSummary.yaml b/docs/openapi/apis/cf/latest/components/schemas/InfoUsageSummary.yaml new file mode 100644 index 00000000000..f9efdb19abd --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/InfoUsageSummary.yaml @@ -0,0 +1,40 @@ +type: object +properties: + usage_summary: + type: object + description: A high-level summary of usage across the entire Cloud Foundry installation + properties: + started_instances: + type: integer + description: Total number of process instances in the `STARTED` state + memory_in_mb: + type: integer + description: Sum of memory usage of all tasks in the `RUNNING` state and all process instances in the `STARTED` state + routes: + type: integer + description: Total number of routes + service_instances: + type: integer + description: Total number of managed service instances + reserved_ports: + type: integer + description: Total number of reserved ports + domains: + type: integer + description: Total number of private domains + per_app_tasks: + type: integer + description: Total number of running tasks + service_keys: + type: integer + description: Total number of service keys + links: + type: object + description: Links to related resources + properties: + self: + allOf: + - $ref: './Link.yaml' + - description: Link to the current endpoint +description: |- + A high-level summary of usage across the entire Cloud Foundry installation. 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/components/schemas/Job.yaml b/docs/openapi/apis/cf/latest/components/schemas/Job.yaml index d7fb196b7fe..41bcedce8bf 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Job.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Job.yaml @@ -4,28 +4,32 @@ allOf: - properties: operation: type: string - description: The type of operation the job is performing + description: Current desired operation of the job on a model state: type: string - description: The current state of the job + description: |- + State of the job; valid values are `PROCESSING`, `POLLING`, `COMPLETE`, or `FAILED` + + > **Note:** `POLLING` happens during asynchronous services operations that require polling the last operation from the service broker. enum: - PROCESSING + - POLLING - COMPLETE - FAILED - - POLLING errors: type: array - description: Any errors encountered during job execution + description: Array of errors that occurred while processing the job items: $ref: './Error.yaml' warnings: type: array - description: Any warnings encountered during job execution + description: Array of warnings that occurred while processing the job items: $ref: './Warning.yaml' links: type: object additionalProperties: true + description: Links to related resources properties: self: $ref: './Link.yaml' diff --git a/docs/openapi/apis/cf/latest/components/schemas/JobList.yaml b/docs/openapi/apis/cf/latest/components/schemas/JobList.yaml index 061f73e43a2..99a31ef19a8 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/JobList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/JobList.yaml @@ -1,8 +1,10 @@ type: object properties: pagination: - $ref: '#/components/schemas/Pagination' + $ref: './Pagination.yaml' resources: type: array items: - $ref: '#/components/schemas/Job' + $ref: './Job.yaml' + description: List of jobs +description: A list of jobs diff --git a/docs/openapi/apis/cf/latest/components/schemas/KeyCredentialBinding.yaml b/docs/openapi/apis/cf/latest/components/schemas/KeyCredentialBinding.yaml index 644d52dd99c..afcc43990c9 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/KeyCredentialBinding.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/KeyCredentialBinding.yaml @@ -6,33 +6,46 @@ allOf: type: string enum: - key - description: Type of credential binding + description: Either `app` or `key` name: type: string - description: Name of the credential binding + description: Name of the binding. `null` when it's not defined. last_operation: $ref: './ServiceCredentialBindingLastOperation.yaml' + description: The last operation of this binding relationships: type: object properties: service_instance: $ref: './RelationshipToOne.yaml' - description: Relationships for the credential binding + description: The service instance that this binding is originated from + description: Relationships for the service credential binding links: type: object properties: self: $ref: './Link.yaml' + description: Link to this service credential binding details: $ref: './Link.yaml' + description: Link to the details of this service credential binding service_instance: $ref: './Link.yaml' + description: Link to the service instance that this binding is originated from + parameters: + $ref: './Link.yaml' + description: Link to the parameters that this binding was created with + description: Links to related resources metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service credential binding included: $ref: './IncludedResources.yaml' - description: Additional related resources included in the response when using the include parameter + description: Additional related resources included in the response when using the `include` parameter required: - - type - - relationships - - links \ No newline at end of file + - type + - relationships + - links +description: |- + A service credential binding of type `key`; it only retrieves the details of the service instance and makes them + available to the developer. Bindings of type `key` are only valid for managed service instances. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstance.yaml b/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstance.yaml index 519f4675f18..2ce61cfbefc 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstance.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstance.yaml @@ -6,7 +6,7 @@ allOf: type: string enum: - managed - description: Type of service instance + description: Either `managed` or `user-provided` name: type: string description: Name of the service instance @@ -14,62 +14,65 @@ allOf: type: array items: type: string - description: Tags for the service instance - syslog_drain_url: - type: [string, "null"] - format: uri - description: URL for syslog drain - route_service_url: - type: [string, "null"] - format: uri - description: URL for route service + description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env dashboard_url: type: [string, "null"] format: uri - description: URL for service dashboard + description: The URL to the service instance dashboard (or null if there is none); only shown when type is `managed` maintenance_info: - type: object - properties: - version: - type: string - description: Version of maintenance info - description: - type: [string, "null"] - description: Description of maintenance info + $ref: './ServiceInstanceMaintenanceInfo.yaml' + description: Information about the version of this service instance; only shown when type is `managed` upgrade_available: type: boolean - description: Whether an upgrade is available + description: Whether or not an upgrade of this service instance is available on the current Service Plan; details are available in the maintenance_info object; only shown when type is `managed` + broker_provided_metadata: + $ref: './ServiceInstanceBrokerProvidedMetadata.yaml' + description: Metadata provided by the service broker about this service instance; only shown when type is `managed` last_operation: $ref: './ServiceInstanceLastOperation.yaml' + description: The last operation of this service instance relationships: type: object properties: space: $ref: './RelationshipToOne.yaml' + description: The space the service instance is contained in service_plan: $ref: './RelationshipToOne.yaml' + description: The service plan the service instance relates to; only shown when type is `managed` description: Relationships for the service instance links: type: object properties: self: $ref: './Link.yaml' + description: Link to this service instance space: $ref: './Link.yaml' + description: Link to the space the service instance is contained in service_plan: $ref: './Link.yaml' + description: Link to the service plan the service instance relates to parameters: $ref: './Link.yaml' + description: Link to the parameters the service instance was created or updated with + shared_spaces: + $ref: './Link.yaml' + description: Link to the spaces this service instance has been shared to service_credential_bindings: $ref: './Link.yaml' + description: Link to the service credential bindings for this service instance service_route_bindings: $ref: './Link.yaml' - shared_spaces: - $ref: './Link.yaml' + description: Link to the service route bindings for this service instance + description: Links to related resources metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service instance required: - type - name - relationships - - links \ No newline at end of file + - links +description: |- + A managed service instance is an instantiation of a [service offering](#service-offerings) registered with CF. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstanceCreate.yaml b/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstanceCreate.yaml new file mode 100644 index 00000000000..a7dd94a9f24 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstanceCreate.yaml @@ -0,0 +1,42 @@ +type: object +required: + - type + - name + - relationships +properties: + type: + type: string + enum: + - managed + description: Must be `managed` + name: + type: string + description: Name of the service instance; must be unique within the space (case-sensitive) + tags: + type: array + items: + type: string + description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env + parameters: + type: object + description: A JSON object that is passed to the service broker + relationships: + type: object + required: + - space + - service_plan + properties: + space: + $ref: './RelationshipToOne.yaml' + description: The space in which to create the service instance + service_plan: + $ref: './RelationshipToOne.yaml' + description: The service plan from which to create the service instance + description: Relationships for the service instance + metadata: + $ref: './Metadata.yaml' + description: Labels and annotations applied to the service instance +description: |- + Parameters for creating a managed service instance. + + If failures occur when creating managed service instances, the API might execute orphan mitigation steps accordingly to cases outlined in the [OSBAPI specification](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) diff --git a/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstanceUpdate.yaml b/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstanceUpdate.yaml new file mode 100644 index 00000000000..16090789c84 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ManagedServiceInstanceUpdate.yaml @@ -0,0 +1,43 @@ +type: object +properties: + name: + type: string + description: Name of the service instance + tags: + type: array + items: + type: string + description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env + parameters: + type: object + description: A JSON object that is passed to the service broker + relationships: + type: object + properties: + service_plan: + $ref: './RelationshipToOne.yaml' + description: The service plan from which to create the service instance + description: Relationships for the service instance + maintenance_info: + type: object + required: + - version + properties: + version: + type: string + description: A semantic version value that must match the `version` in the `maintenance_info` for the service instance plan in the updated broker catalog + description: If provided, must have the `version` field; `version` must be a semantic version value and it must match the `version` in the `maintenance_info` for the service instance plan in the updated broker catalog. Any other value for `version` will cause a `MaintenanceInfoConflict` error + metadata: + $ref: './Metadata.yaml' + description: Labels and annotations applied to the service_instance +description: |- + Optional parameters for updating a managed service instance. + + Some updates can be performed entirely within the Cloud Controller in which case the response is synchronous. Some updates require communication with the service broker, in which case the response will be asynchronous. The response will be asynchronous if any of these parameters are specified: + + * `parameters` + * `service_plan` + * `maintenance_info` + * `name` - when the service offering has `allow_context_updates` feature enabled + + Otherwise the response will be synchronous. diff --git a/docs/openapi/apis/cf/latest/components/schemas/Manifest.yaml b/docs/openapi/apis/cf/latest/components/schemas/Manifest.yaml new file mode 100644 index 00000000000..b199b574924 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/Manifest.yaml @@ -0,0 +1,184 @@ +type: string +description: |- + A manifest is a method for applying bulk configurations to apps and their underlying processes. + + Manifests are in the YAML format. However, anchors and aliases are not supported. + + ### The manifest schema + + ```yaml + --- + version: 1 + applications: + - name: app1 + buildpacks: + - ruby_buildpack + - java_buildpack + env: + VAR1: value1 + VAR2: value2 + features: + ssh: true + revisions: true + service-binding-k8s: false + file-based-vcap-services: false + routes: + - route: route.example.com + - route: another-route.example.com + protocol: http2 + - route: route-with-options.example.com + options: + loadbalancing: least-connection + services: + - my-service1 + - my-service2 + - name: my-service-with-arbitrary-params + binding_name: my-binding + parameters: + key1: value1 + key2: value2 + stack: cflinuxfs4 + metadata: + annotations: + contact: "bob@example.com jane@example.com" + labels: + sensitive: true + processes: + - type: web + command: start-web.sh + disk_quota: 512M + health-check-type: http + health-check-http-endpoint: /healthcheck + health-check-invocation-timeout: 10 + health-check-interval: 5 + readiness-health-check-type: http + readiness-health-check-http-endpoint: /ready + readiness-health-check-invocation-timeout: 10 + readiness-health-check-interval: 5 + instances: 3 + memory: 500M + log-rate-limit-per-second: 1KB + timeout: 10 + user: vcap + - type: worker + command: start-worker.sh + disk_quota: 1G + health-check-type: process + instances: 2 + memory: 256M + log-rate-limit-per-second: 1KB + timeout: 15 + - name: app2 + env: + VAR1: value1 + processes: + - type: web + instances: 1 + memory: 256M + log-rate-limit-per-second: 1KB + sidecars: + - name: authenticator + process_types: [ 'web', 'worker' ] + command: bundle exec run-authenticator + memory: 800M + + - name: upcaser + process_types: [ 'worker' ] + command: ./tr-server + memory: 2G + ``` + + #### Space-level configuration + + Name | Type | Description + ----- | ---- | ----------- + **applications** | _array of [app configurations](#space-manifest-app-level-configuration)_ | Configurations for apps in the space + **version** | _integer_ | The manifest schema version; currently the only valid version is `1`, defaults to `1` if not provided + + #### App-level configuration + + This configuration is specified per application and applies to all of the application's processes. + + Name | Type | Description + ----- | ---- | ----------- + **name** | _string_ | Name of the app + **lifecycle** | _string_ | Type of the lifecycle; valid values are `buildpack`, `cnb`, `docker`. Defaults to `buildpack`, unless the **docker** property is present. + **buildpacks** | _list of strings_ | a) An empty array, which will automatically select the appropriate default buildpack according to the coding language (incompatible with **lifecycle: cnb**) b) An array of one or more URLs pointing to buildpacks c) An array of one or more installed buildpack names. Replaces the legacy `buildpack` field + **docker** | _object_ | If present, the created app will have Docker lifecycle type; the value of this key is ignored by the API but may be used by clients to source the registry address of the image and credentials, if needed; the [generate manifest endpoint](#generate-a-manifest-for-an-app) will return the registry address of the image and username provided with this key + **env** | _object_ | A key-value mapping of environment variables to be used for the app when running + **features** | _object_ | A key-value mapping of feature names to booleans (true = enabled, false = disabled) + **no-route** | _boolean_ | When set to `true`, any routes specified with the `routes` attribute will be ignored and any existing routes will be removed + **processes** | _array of [process configurations](#space-manifest-process-level-configuration)_ | List of configurations for individual process types + **random-route** | _boolean_ | Creates a random route for the app if `true`; if `routes` is specified, if the app already has routes, or if `no-route` is specified, this field is ignored regardless of its value + **default-route** | _boolean_ | If true, a route for the app will be created using the app name as the hostname and the containing organization's default domain as the domain; if `routes` is specified, if the app already has routes, or if `no-route` is specified, this field is ignored regardless of its value + **routes** | _array of [route configurations](#space-manifest-route-level-configuration)_ | List declaring HTTP and TCP routes to be mapped to the app. + **services** | _array of [service configurations](#space-manifest-service-level-configuration)_ | A list of service-instances to bind to the app + **sidecars** | _array of [sidecar configurations](#space-manifest-sidecar-level-configuration)_ | A list of configurations for individual sidecars + **stack** | _string_ | The root filesystem to use with the buildpack, for example `cflinuxfs4` + **metadata.labels** | _[label object](#labels)_ | Labels applied to the app + **metadata.annotations** | _[annotation object](#annotations)_ | Annotations applied to the app + **buildpack** | _string_ | **DEPRECATED in favor of the `buildpacks` field above** + + #### Process-level configuration + + This configuration is for the individual process. Each process is created if it does not already exist. + + For backwards compatibility, the `web` process configuration may be placed at the top level of the application configuration, rather than listed under `processes`. However, if there is a process with `type: web` listed under `processes`, this configuration will override any at the top level. + + Name | Type | Description + ---- | ---- | ----------- + **type** | _string_ | **(Required)** The identifier for the processes to be configured + **command** | _string_ | The command used to start the process; this overrides start commands from [Procfiles](#procfiles) and buildpacks + **user** | _string_ | The user under which the process runs + **disk_quota** | _string_ | The disk limit for all instances of the web process; this attribute requires a unit of measurement: `B`, `K`, `KB`, `M`, `MB`, `G`, `GB`, `T`, or `TB` in upper case or lower case + **health-check-http-endpoint** | _string_ | Endpoint called to determine if the app is healthy + **health-check-interval** | _integer_ | The interval in seconds between health check requests + **health-check-invocation-timeout** | _integer_ | The timeout in seconds for individual health check requests for http and port health checks + **health-check-type** | _string_ | Type of health check to perform; `none` is deprecated and an alias to `process` + **readiness-health-check-http-endpoint** | _string_ | Endpoint called to determine if the app is ready to receive traffic + **readiness-health-check-interval** | _integer_ | The interval in seconds between readiness health check requests + **readiness-health-check-invocation-timeout** | _integer_ | The timeout in seconds for individual readiness health check requests for http and port readiness checks + **readiness-health-check-type** | _string_ | Type of readiness health check to perform; valid values: `http`, `port`, `process` + **instances** | _integer_ | The number of instances to run + **memory** | _string_ | The memory limit for all instances of the web process; this attribute requires a unit of measurement: `B`, `K`, `KB`, `M`, `MB`, `G`, `GB`, `T`, or `TB` in upper case or lower case + **log-rate-limit-per-second** | _string_ | The log rate limit for all the instances of the process; this attribute requires a unit of measurement: `B`, `K`, `KB`, `M`, `MB`, `G`, `GB`, `T`, or `TB` in upper case or lower case, or -1 or 0 + **timeout** | _integer_ | Time in seconds at which the health-check will report failure + + #### Route-level configuration + + This configuration is for _creating_ mappings between the app and a route. Each route is created if it does not already exist. The protocol will be updated for any existing route mapping. + + Name | Type | Description + ---- | ---- | ----------- + **route** | _string_ | **(Required)** The route URI. Example: `host.domain.com` + **protocol** | _string_ | Protocol to use for this route. Valid protocols are `http1`, `http2`, and `tcp` + **options** | _object_ | A key-value mapping of configuration [options](#space-manifest-per-route-options-level-configuration) to be applied to the specific application route + + #### Per-Route Options-level configuration + + This configuration allows additional key-value options for the specific application route. + + Name | Type | Description + ---- | ---- | ----------- + **loadbalancing** | _string_ | The load-balancer associated with this route. Valid values are `round-robin` and `least-connection` + + #### Service-level configuration + + This configuration is _creating_ new service bindings between the app and a service instance. The `services` field can take either an array of service instance name strings or an array of the following service-level fields. + + Name | Type | Description + ---- | ---- | ----------- + **name** | _string_ | **(Required)** The name of the service instance to be bound to + **binding_name** | _string_ | The name of the service binding to be created + **parameters** | _object_ | A map of arbitrary key/value pairs to send to the service broker during binding + + #### Sidecar-level configuration + + This configuration is for the individual sidecar. Each sidecar is created if it does not already exist. + + Name | Type | Description + ---- | ---- | ----------- + **name** | _string_ | **(Required)** The identifier for the sidecars to be configured + **command** | _string_ | The command used to start the sidecar + **process_types** | _list of strings_ | List of processes to associate sidecar with + **memory** | _integer_ | Memory in MB that the sidecar will be allocated diff --git a/docs/openapi/apis/cf/latest/components/schemas/Organization.yaml b/docs/openapi/apis/cf/latest/components/schemas/Organization.yaml index 415e5f87662..6da89e3402d 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Organization.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Organization.yaml @@ -10,26 +10,34 @@ allOf: description: Whether an organization is suspended or not; non-admins will be blocked from creating, updating, or deleting resources in a suspended organization relationships: type: object + description: Relationships for the organization properties: quota: $ref: './RelationshipToOne.yaml' - description: The quota applied to the organization + description: The quota applied to the organization metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the organization links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL to get this organization + description: The URL of this organization domains: $ref: './Link.yaml' - description: The URL to get the domains for this organization - quota: - $ref: './Link.yaml' - description: The URL to get the quota for this organization + description: The URL to list the domains available in this organization default_domain: $ref: './Link.yaml' description: The URL to get the default domain for this organization + quota: + $ref: './Link.yaml' + description: The URL of the organization quota applied to this organization + required: + - name + - suspended + - relationships + - links description: > An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains. diff --git a/docs/openapi/apis/cf/latest/components/schemas/OrganizationDefaultIsolationSegmentRelationship.yaml b/docs/openapi/apis/cf/latest/components/schemas/OrganizationDefaultIsolationSegmentRelationship.yaml new file mode 100644 index 00000000000..b660f3071e3 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/OrganizationDefaultIsolationSegmentRelationship.yaml @@ -0,0 +1,23 @@ +type: object +properties: + data: + oneOf: + - $ref: './Relationship.yaml' + - type: 'null' + description: Isolation segment relationship; apps will run in this isolation segment; `null` when the organization has no default isolation segment + links: + type: object + description: Links to related resources + properties: + self: + $ref: './Link.yaml' + description: The URL of this default isolation segment relationship + related: + $ref: './Link.yaml' + description: The URL of the isolation segment that is the default for this organization +required: + - data + - links +description: |- + A to-one relationship between an organization and the isolation segment in which its apps run by default. + Only isolation segments that are entitled to the organization are eligible to be the default isolation segment. diff --git a/docs/openapi/apis/cf/latest/components/schemas/OrganizationList.yaml b/docs/openapi/apis/cf/latest/components/schemas/OrganizationList.yaml index f23e060b888..2bc94c5a5f5 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/OrganizationList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/OrganizationList.yaml @@ -2,8 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of organizations resources: type: array items: $ref: './Organization.yaml' + description: List of organizations description: A paginated list of organizations diff --git a/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuota.yaml b/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuota.yaml index 5118f0cc408..d51a262de80 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuota.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuota.yaml @@ -9,21 +9,21 @@ allOf: type: object description: Quotas that affect applications and application sub-resources properties: - per_process_memory_in_mb: - type: [integer, "null"] - description: Maximum memory for a single process or task total_memory_in_mb: type: [integer, "null"] - description: Total memory allowed for all the started processes and running tasks in an organization - total_instances: + description: Total memory allowed for all the started processes and running tasks in an organization; `null` means unlimited + per_process_memory_in_mb: type: [integer, "null"] - description: Total instances of all the started processes allowed in an organization - log_rate_limit_in_bytes_per_second: + description: Maximum memory for a single process or task; `null` means unlimited + total_instances: type: [integer, "null"] - description: Total log rate limit allowed for all the started processes and running tasks in an organization + description: Total instances of all the started processes allowed in an organization; `null` means unlimited per_app_tasks: type: [integer, "null"] - description: Maximum number of running tasks in an organization + description: Maximum number of running tasks in an organization; `null` means unlimited + log_rate_limit_in_bytes_per_second: + type: [integer, "null"] + description: Total log rate limit allowed for all the started processes and running tasks in an organization; `null` means unlimited services: type: object description: Quotas that affect services @@ -33,43 +33,48 @@ allOf: description: Specifies whether instances of paid service plans can be created total_service_instances: type: [integer, "null"] - description: Total number of service instances allowed in an organization + description: Total number of service instances allowed in an organization; `null` means unlimited total_service_keys: type: [integer, "null"] - description: Total number of service keys allowed in an organization + description: Total number of service keys allowed in an organization; `null` means unlimited routes: type: object description: Quotas that affect routes properties: total_routes: type: [integer, "null"] - description: Total number of routes allowed in an organization + description: Total number of routes allowed in an organization; `null` means unlimited total_reserved_ports: type: [integer, "null"] - description: Total number of ports that are reservable by routes in an organization + description: Total number of ports that are reservable by routes in an organization; `null` means unlimited domains: type: object description: Quotas that affect domains properties: total_domains: type: [integer, "null"] - description: Total number of domains that can be scoped to an organization + description: Total number of domains that can be scoped to an organization; `null` means unlimited relationships: type: object + description: Relationships for the organization quota properties: organizations: $ref: './RelationshipToMany.yaml' - description: A relationship to the organizations where the quota is applied - metadata: - $ref: './Metadata.yaml' + description: A relationship to the organizations where the quota is applied links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL to get this organization quota - organizations: - $ref: './Link.yaml' - description: The URL to get the organizations for this quota + description: The URL of this organization quota + required: + - name + - apps + - services + - routes + - domains + - relationships + - links description: > Organization quotas are named sets of memory, log rate, service, and instance usage quotas. For example, one organization quota might allow up to 10 services, 10 routes, and 2 GB of RAM, while another might offer 100 services, 100 routes, and 10 GB of RAM. diff --git a/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuotaList.yaml b/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuotaList.yaml index cf47a8f8287..0b5366d4310 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuotaList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/OrganizationQuotaList.yaml @@ -1,9 +1,11 @@ type: object -allOf: - - $ref: './Pagination.yaml' - - properties: - resources: - type: array - items: - $ref: './OrganizationQuota.yaml' +properties: + pagination: + $ref: './Pagination.yaml' + description: Pagination information for the list of organization quotas + resources: + type: array + items: + $ref: './OrganizationQuota.yaml' + description: List of organization quotas description: A paginated list of organization quotas diff --git a/docs/openapi/apis/cf/latest/components/schemas/OrganizationUsageSummary.yaml b/docs/openapi/apis/cf/latest/components/schemas/OrganizationUsageSummary.yaml new file mode 100644 index 00000000000..7bea15b4c24 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/OrganizationUsageSummary.yaml @@ -0,0 +1,45 @@ +type: object +properties: + usage_summary: + type: object + description: The memory and app instance usage summary for the organization + properties: + started_instances: + type: integer + description: Total instances of all the started processes in the organization + memory_in_mb: + type: integer + description: Total memory used by all the started processes and running tasks in the organization + routes: + type: integer + description: Total number of routes in the organization + service_instances: + type: integer + description: Total number of service instances in the organization + reserved_ports: + type: integer + description: Total number of ports reserved by routes in the organization + domains: + type: integer + description: Total number of domains scoped to the organization + per_app_tasks: + type: integer + description: Total number of running tasks in the organization + service_keys: + type: integer + description: Total number of service keys in the organization + links: + type: object + description: Links to related resources + properties: + self: + $ref: './Link.yaml' + description: The URL of this usage summary + organization: + $ref: './Link.yaml' + description: The URL of the organization this usage summary belongs to +required: + - usage_summary + - links +description: |- + The memory and app instance usage summary for an organization. diff --git a/docs/openapi/apis/cf/latest/components/schemas/Package.yaml b/docs/openapi/apis/cf/latest/components/schemas/Package.yaml index 2d5852aeb7d..3f01bb45cd6 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Package.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Package.yaml @@ -4,23 +4,33 @@ allOf: - properties: type: type: string - description: Type of the package; valid values are bits or docker + description: Package type; valid values are `bits`, `docker` enum: - bits - docker data: type: object - description: Data for package type + description: |- + Data for package type. + + **Bits package data** + + A bits package is used to upload source code for an app to. The bits package will provide an `upload` link to which a zip file should be uploaded. Bits packages carry `data.error` and `data.checksum`. + + **Docker package data** + + A Docker package references a Docker image from a registry. Docker packages carry `data.image`, `data.username`, and `data.password`. properties: error: type: [string, 'null'] description: If an error occurs this field will contain the error message checksum: type: object + description: The checksum of the uploaded bits properties: type: type: string - description: The checksum type, for example sha256 + description: 'The checksum type, for example: `sha256`' value: type: [string, 'null'] description: The checksum value; this will be populated after bits are uploaded @@ -35,7 +45,7 @@ allOf: description: The password for the image's registry state: type: string - description: State of the package; valid states are AWAITING_UPLOAD, PROCESSING_UPLOAD, READY, FAILED, COPYING, or EXPIRED + description: State of the package; valid states are `AWAITING_UPLOAD`, `PROCESSING_UPLOAD`, `READY`, `FAILED`, `COPYING`, `EXPIRED` enum: - AWAITING_UPLOAD - PROCESSING_UPLOAD @@ -44,22 +54,32 @@ allOf: - COPYING - EXPIRED relationships: - $ref: './Relationships.yaml' + type: object + description: The relationships of the package + properties: + app: + $ref: './RelationshipToOne.yaml' + description: The app the package belongs to metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the package links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' description: The URL to get this package upload: $ref: './Link.yaml' - description: The URL to upload the package bits + description: The URL to upload the package bits; present only on packages of type `bits` download: $ref: './Link.yaml' - description: The URL to download the package bits + description: The URL to download the package bits; present only on packages of type `bits` app: $ref: './Link.yaml' - description: The URL to get the app for this package -description: 'A package represents an application"s "source code" - either raw bits or a pointer to these bits. Packages are used to create builds, which result in a droplet that can be deployed.' + description: The URL to get the app the package belongs to +description: |- + A package is an application's 'source code'; either raw bits for your application or a pointer to these bits. + + In Cloud Foundry, packages are staged to produce an executable droplet. We currently support raw bits and Docker packages. diff --git a/docs/openapi/apis/cf/latest/components/schemas/PackageList.yaml b/docs/openapi/apis/cf/latest/components/schemas/PackageList.yaml index 2b8672fbf47..873f3d2cf28 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/PackageList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/PackageList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of packages resources: type: array + description: The list of packages items: $ref: './Package.yaml' +description: A paginated list of packages diff --git a/docs/openapi/apis/cf/latest/components/schemas/Process.yaml b/docs/openapi/apis/cf/latest/components/schemas/Process.yaml index f00637fe749..60c7dbd482b 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Process.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Process.yaml @@ -29,21 +29,33 @@ allOf: description: The log rate in bytes per second allocated per instance health_check: $ref: './HealthCheck.yaml' + description: The health check to perform on the process readiness_health_check: - $ref: './HealthCheck.yaml' + $ref: './ReadinessHealthCheck.yaml' + description: The readiness health check to perform on the process + process_instances: + type: array + items: + $ref: './ProcessInstance.yaml' + description: The instances of the process; this key is only present when `process_instances` is requested via the `embed` query parameter (experimental) relationships: type: object + description: Relationships to other resources properties: app: $ref: './RelationshipToOne.yaml' + description: The app the process belongs to revision: oneOf: - $ref: './RelationshipToOne.yaml' - type: 'null' + description: The app revision the process is currently running metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the process links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' @@ -60,4 +72,7 @@ allOf: stats: $ref: './Link.yaml' description: The URL to get the stats for this process + process_instances: + $ref: './Link.yaml' + description: The URL to get the instances for this process description: 'A process defines the runnable units of an app' diff --git a/docs/openapi/apis/cf/latest/components/schemas/ProcessInstance.yaml b/docs/openapi/apis/cf/latest/components/schemas/ProcessInstance.yaml new file mode 100644 index 00000000000..845787602dd --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ProcessInstance.yaml @@ -0,0 +1,16 @@ +type: object +properties: + index: + type: integer + description: The zero-based index of the process instance + state: + type: string + enum: ["RUNNING", "CRASHED", "STARTING", "STOPPING", "DOWN"] + description: 'The state of the process instance (possible values: `RUNNING`, `CRASHED`, `STARTING`, `STOPPING`, `DOWN`)' + since: + type: integer + description: Number of seconds since the process instance entered its current state +description: |- + The process instance object (experimental) + + A lightweight view of a process instance state, containing only the `index`, `state`, and `since` fields. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ProcessInstanceList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ProcessInstanceList.yaml new file mode 100644 index 00000000000..7e3cb1c2e32 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ProcessInstanceList.yaml @@ -0,0 +1,18 @@ +type: object +properties: + resources: + type: array + items: + $ref: './ProcessInstance.yaml' + description: The instances of the process + links: + type: object + description: Links to related resources + properties: + self: + $ref: './Link.yaml' + description: The URL to get the instances for this process + process: + $ref: './Link.yaml' + description: The URL to get the process these instances belong to +description: 'A list of process instances (experimental)' diff --git a/docs/openapi/apis/cf/latest/components/schemas/ProcessList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ProcessList.yaml index b54d8690488..ed48a3144e5 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ProcessList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ProcessList.yaml @@ -1,9 +1,11 @@ -allOf: - - $ref: './Pagination.yaml' - - type: object - properties: - resources: - type: array - items: - $ref: './Process.yaml' -description: 'A list of processes' +type: object +properties: + pagination: + $ref: './Pagination.yaml' + description: Pagination information for the list of processes + resources: + type: array + items: + $ref: './Process.yaml' + description: List of processes +description: 'A paginated list of processes' diff --git a/docs/openapi/apis/cf/latest/components/schemas/ProcessStat.yaml b/docs/openapi/apis/cf/latest/components/schemas/ProcessStat.yaml new file mode 100644 index 00000000000..7fc207c04b5 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ProcessStat.yaml @@ -0,0 +1,87 @@ +type: object +properties: + type: + type: string + description: Process type; a unique identifier for processes belonging to an app + index: + type: integer + description: The zero-based index of running instances + instance_guid: + type: string + description: The unique identifier of the instance + state: + type: string + enum: ["RUNNING", "CRASHED", "STARTING", "STOPPING", "DOWN"] + description: The state of the instance; valid values are `RUNNING`, `CRASHED`, `STARTING`, `STOPPING`, `DOWN` + routable: + type: [boolean, 'null'] + description: Whether or not the instance is routable (determined by the readiness check of the app). If app readiness checks and routability are unsupported by Diego, this will return as `null`. + usage: + type: object + description: Object containing actual usage data for the instance; the value is `{}` when usage data is unavailable + properties: + time: + type: string + format: date-time + description: The time when the usage was requested + cpu: + type: number + description: The current cpu usage of the instance + cpu_entitlement: + type: [number, 'null'] + description: The current cpu usage relative to the instance's cpu entitlement; the value is `null` when cpu entitlement data is unavailable + mem: + type: integer + description: The current memory usage of the instance + disk: + type: integer + description: The current disk usage of the instance + log_rate: + type: integer + description: The current logging usage of the instance + host: + type: string + description: The host the instance is running on + instance_internal_ip: + type: string + description: The internal IP address of the instance + instance_ports: + type: [array, 'null'] + description: JSON array of port mappings between the network-exposed port used to communicate with the app (`external`) and port opened to the running process that it can listen on (`internal`). Clients shall interprete `0` and `null` as non-existing port. + items: + type: object + properties: + external: + type: [integer, 'null'] + description: The network-exposed port used to communicate with the app + internal: + type: [integer, 'null'] + description: The port opened to the running process that it can listen on + external_tls_proxy_port: + type: [integer, 'null'] + description: The network-exposed port of the TLS proxy in front of the app + internal_tls_proxy_port: + type: [integer, 'null'] + description: The port of the TLS proxy in front of the running process + uptime: + type: integer + description: The uptime in seconds for the instance + mem_quota: + type: [integer, 'null'] + description: The current maximum memory allocated for the instance; the value is `null` when memory quota data is unavailable + disk_quota: + type: [integer, 'null'] + description: The current maximum disk allocated for the instance; the value is `null` when disk quota data is unavailable + log_rate_limit: + type: [integer, 'null'] + description: The current maximum log rate allocated for the instance; the value `-1` is unlimited, the value is `null` when the log_rate_limit is unavailable + fds_quota: + type: integer + description: The maximum file descriptors the instance is allowed to use + isolation_segment: + type: [string, 'null'] + description: The current isolation segment that the instance is running on; the value is `null` when the instance is not placed on a particular isolation segment + details: + type: [string, 'null'] + description: Information about errors placing the instance; the value is `null` if there are no placement errors +description: 'The process stats object provides information about the status of an individual instance of a process' diff --git a/docs/openapi/apis/cf/latest/components/schemas/ProcessStats.yaml b/docs/openapi/apis/cf/latest/components/schemas/ProcessStats.yaml index 2a532cb3b14..8770c689742 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ProcessStats.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ProcessStats.yaml @@ -3,37 +3,6 @@ properties: resources: type: array items: - type: object - properties: - type: - type: string - index: - type: integer - state: - type: string - enum: ["RUNNING", "CRASHED", "STARTING", "DOWN", "STOPPING"] - host: - type: string - uptime: - type: integer - mem_quota: - type: [integer, 'null'] - disk_quota: - type: [integer, 'null'] - log_rate_limit: - type: [integer, 'null'] - usage: - type: object - properties: - time: - type: string - format: date-time - cpu: - type: number - mem: - type: integer - disk: - type: integer - log_rate: - type: integer -description: 'Statistics for a process' + $ref: './ProcessStat.yaml' + description: The stats for each instance of the process +description: 'Process stats are objects that represent the individual instances of a process' diff --git a/docs/openapi/apis/cf/latest/components/schemas/ReadinessHealthCheck.yaml b/docs/openapi/apis/cf/latest/components/schemas/ReadinessHealthCheck.yaml new file mode 100644 index 00000000000..50caa322850 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ReadinessHealthCheck.yaml @@ -0,0 +1,21 @@ +type: object +properties: + type: + type: string + enum: ["http", "port", "process"] + default: process + description: The type of health check to perform; valid values are `http`, `port`, and `process`; default is `process` + data: + type: object + description: Configuration for the readiness health check + properties: + invocation_timeout: + type: [integer, 'null'] + description: The timeout in seconds for individual health check requests for `http` and `port` health checks + interval: + type: [integer, 'null'] + description: The interval in seconds between health check requests + endpoint: + type: [string, 'null'] + description: The endpoint called to determine if the app is ready; this key is only present for `http` health checks +description: 'The readiness health check to perform on the process' diff --git a/docs/openapi/apis/cf/latest/components/schemas/RelationshipToOne.yaml b/docs/openapi/apis/cf/latest/components/schemas/RelationshipToOne.yaml index 89f05cdb347..996685ecb0d 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/RelationshipToOne.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/RelationshipToOne.yaml @@ -1,8 +1,10 @@ type: object properties: data: - type: [object, "null"] - $ref: './Relationship.yaml' + oneOf: + - $ref: './Relationship.yaml' + - type: "null" + description: The related resource, or `null` when the relationship is not set links: type: object properties: diff --git a/docs/openapi/apis/cf/latest/components/schemas/ResourceMatch.yaml b/docs/openapi/apis/cf/latest/components/schemas/ResourceMatch.yaml index 941dbd8c780..c0caca0c056 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ResourceMatch.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ResourceMatch.yaml @@ -2,17 +2,10 @@ type: object properties: resources: type: array + description: List of resources to check for in the resource cache items: - type: object - properties: - checksum: - type: object - properties: - value: - type: string - size_in_bytes: - type: integer - path: - type: string - mode: - type: string + $ref: './ResourceMatchObject.yaml' +required: + - resources +description: |- + This endpoint matches given resource SHA-1/file size pairs against the Cloud Controller cache and reports the subset that describes already cached files. This is usually used to avoid uploading duplicate files when pushing an app which has only been partially changed. The `path` and `mode` fields are not used when matching. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ResourceMatchObject.yaml b/docs/openapi/apis/cf/latest/components/schemas/ResourceMatchObject.yaml new file mode 100644 index 00000000000..3f8309ff71a --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ResourceMatchObject.yaml @@ -0,0 +1,24 @@ +type: object +properties: + checksum: + type: object + description: Checksum of the file + properties: + value: + type: string + description: SHA-1 hash of file + required: + - value + size_in_bytes: + type: integer + description: Size of file in bytes + path: + type: string + description: Path to the file, relative to app root + mode: + type: string + description: File mode, i.e. POSIX file permissions; defaults to 0744 +required: + - checksum + - size_in_bytes +description: A fingerprint of an application file that has previously been pushed to Cloud Foundry diff --git a/docs/openapi/apis/cf/latest/components/schemas/Revision.yaml b/docs/openapi/apis/cf/latest/components/schemas/Revision.yaml index 53b19eeb582..6e4c32c50f0 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Revision.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Revision.yaml @@ -2,35 +2,82 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the revision + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated version: type: integer - description: Version number of the revision + description: Human-readable identifier for the revision; starts at 1, increments by 1 for each new revision of the app, and rolls back over to 1 at 9999 + droplet: + type: object + description: The droplet used by a process running the revision + properties: + guid: + type: string + format: uuid + description: The GUID of the droplet used by a process running the revision + processes: + $ref: './RevisionProcessSnapshot.yaml' + description: An object representing process types at this revision + sidecars: + type: array + items: + $ref: './RevisionSidecarSnapshot.yaml' + description: The array of sidecars used by processes running the revision description: type: [string, "null"] - description: Description of the revision, created by the user - droplet: - $ref: './RelationshipToOne.yaml' - relationships: - allOf: - - $ref: './Relationships.yaml' - - properties: - app: - $ref: './RelationshipToOne.yaml' - enabled: + description: A short description of the reason for revision + deployable: type: boolean - description: Whether the revision is enabled or not. + description: Indicates if the revision's droplet is staged and the revision can be used to [create a deployment](#create-a-deployment) + relationships: + type: object + description: Relationships to other resources + properties: + app: + $ref: './RelationshipToOne.yaml' + description: The app the revision is associated with metadata: $ref: './Metadata.yaml' + description: |- + `labels`: Labels applied to the revision + + `annotations`: Annotations applied to the revision links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' description: The URL to get this revision app: $ref: './Link.yaml' - description: The URL to get the app for this revision + description: The URL to get the app the revision is associated with environment_variables: $ref: './Link.yaml' description: The URL to get the environment variables for this revision -description: 'An App Revision is an immutable snapshot of an app at a particular point in time. Revisions are identified by a sequential version number. The "current" revision for an app is the revision that is currently deployed for all instances of the app.' +description: |- + Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry. Revisions are not created for Tasks. + + Revision are created when the following is changed: + + * A new droplet is deployed for an app + + * An app is deployed with new environment variables + + * The app is deployed with a new or changed custom start command + + * An app rolls back to a prior revision + + Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field. + + By default the cloud foundry API retains at most 100 revisions per app. diff --git a/docs/openapi/apis/cf/latest/components/schemas/RevisionList.yaml b/docs/openapi/apis/cf/latest/components/schemas/RevisionList.yaml index 5b241ec6fd8..c18f8516f46 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/RevisionList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/RevisionList.yaml @@ -2,7 +2,10 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of revisions resources: type: array items: $ref: './Revision.yaml' + description: List of revisions +description: A paginated list of revisions diff --git a/docs/openapi/apis/cf/latest/components/schemas/RevisionProcessSnapshot.yaml b/docs/openapi/apis/cf/latest/components/schemas/RevisionProcessSnapshot.yaml new file mode 100644 index 00000000000..4014f364554 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/RevisionProcessSnapshot.yaml @@ -0,0 +1,10 @@ +type: object +additionalProperties: + type: object + properties: + command: + type: [string, "null"] + description: The command that the given process type was running at this revision +description: |- + The process snapshot object is a map of process types to objects. + Each object contains the command that the given process type was running at this revision. diff --git a/docs/openapi/apis/cf/latest/components/schemas/RevisionSidecarSnapshot.yaml b/docs/openapi/apis/cf/latest/components/schemas/RevisionSidecarSnapshot.yaml new file mode 100644 index 00000000000..022d1dfe6cc --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/RevisionSidecarSnapshot.yaml @@ -0,0 +1,17 @@ +type: object +properties: + name: + type: string + description: Human-readable name for the sidecar + command: + type: string + description: The command used to start the sidecar + process_types: + type: array + items: + type: string + description: A list of process types the sidecar applies to + memory_in_mb: + type: [integer, "null"] + description: Reserved memory for sidecar +description: A snapshot of a sidecar used by processes running the revision diff --git a/docs/openapi/apis/cf/latest/components/schemas/Role.yaml b/docs/openapi/apis/cf/latest/components/schemas/Role.yaml index f49bb3eb990..383b62d4234 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Role.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Role.yaml @@ -2,10 +2,22 @@ allOf: - $ref: './BaseSchema.yaml' type: object properties: + guid: + type: string + format: uuid + description: Unique identifier for the role + created_at: + type: string + format: date-time + description: The time with zone when the role was created + updated_at: + type: string + format: date-time + description: The time with zone when the role was last updated type: type: string description: |- - Role type. Possible values are: + Role type; see [Valid role types](#valid-role-types). Possible values are: - `organization_user`: A user in the organization - `organization_auditor`: An auditor in the organization - `organization_manager`: A manager in the organization @@ -13,7 +25,7 @@ properties: - `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) + - `space_supporter`: A supporter in the space; users with only the space supporter role are not authorized to use the **V2** API enum: - organization_user - organization_auditor @@ -27,23 +39,18 @@ properties: 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 + $ref: './RelationshipToOne.yaml' + description: A relationship to the user; this is the user that has the role + space: + $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` + organization: + $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` links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' @@ -53,14 +60,14 @@ properties: description: The URL to get the user for this role organization: $ref: './Link.yaml' - description: The URL to get the organization for this role + description: The URL to get the organization for this role; only present for organization roles space: $ref: './Link.yaml' - description: The URL to get the space for this role + description: The URL to get the space for this role; only present for space roles included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter 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. + Roles control access to resources in organizations and spaces. Roles are assigned to users. + + A role is represented as a JSON object consisting of a role type and relationships to the user and to the organization or space the role controls access to. diff --git a/docs/openapi/apis/cf/latest/components/schemas/Route.yaml b/docs/openapi/apis/cf/latest/components/schemas/Route.yaml index d972b356d5c..16ea3358dc7 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Route.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Route.yaml @@ -4,19 +4,43 @@ allOf: - properties: protocol: type: string + enum: + - http + - tcp + description: The protocol supported by the route, based on the route's domain configuration. Valid protocols are `http` and `tcp` host: type: string + description: The hostname for the route; not compatible with routes specifying the `tcp` protocol; must be either a wildcard (*) or be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_) path: type: string + description: The path for the route; not compatible with routes specifying the `tcp` protocol; must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from [RFC 2396](https://tools.ietf.org/html/rfc2396) port: type: [integer, 'null'] + description: The port that the route listens on. Only compatible with routes specifying the `tcp` protocol url: type: string - description: Fully qualified path or address where the route directs traffic + description: The URL for the route; URLs of protocol `http` are a combination of host, domain name, and path; URLs of protocol `tcp` are a combination of domain name and port + destinations: + type: array + items: + $ref: './RouteDestination.yaml' + description: List of destinations for the route relationships: - $ref: './Relationships.yaml' + type: object + properties: + space: + $ref: './RelationshipToOne.yaml' + description: A relationship to the space containing the route. Routes can only be mapped to destinations in that space + domain: + $ref: './RelationshipToOne.yaml' + description: A relationship to the domain of the route + description: Relationships to the space and domain of the route + options: + $ref: './RouteOptions.yaml' + description: Options applied to the route metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the route links: type: object properties: @@ -32,7 +56,9 @@ allOf: destinations: $ref: './Link.yaml' description: The URL to get the destinations for this route + description: Links to related resources included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter -description: A route in Cloud Foundry is used to direct traffic from a URL to an application. +description: |- + Routes are addresses that direct matched network traffic to one or more destinations. Each route is based on a domain name with additional matching criteria (host (subdomain), path, etc). Matched traffic will be distributed across all destinations, based on their configuration (round-robin by default). diff --git a/docs/openapi/apis/cf/latest/components/schemas/RouteDestination.yaml b/docs/openapi/apis/cf/latest/components/schemas/RouteDestination.yaml index 39680cd702c..0af8a71a145 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/RouteDestination.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/RouteDestination.yaml @@ -2,39 +2,65 @@ type: object properties: guid: type: string + format: uuid + description: Unique identifier for the destination app: type: object properties: guid: type: string + format: uuid + description: Unique identifier for the app to route traffic to process: type: object properties: type: type: string + description: Type of the process belonging to the app to route traffic to + description: The process of the app to route traffic to + description: The app to route traffic to + port: + type: integer + description: Port on the destination process to route traffic to weight: type: - integer - 'null' - port: - type: integer + deprecated: true + description: 'Percentage of traffic which will be routed to this destination. **DEPRECATED:** this feature was only available via the experimental Service Mesh routing plane. It is no longer supported.' protocol: type: [string, "null"] + enum: + - http1 + - http2 + - tcp + - null + description: Protocol to use for this destination. Valid protocols are `http1` or `http2` if route protocol is `http`, `tcp` if route protocol is `tcp`. A `null` value will set it either `http1` or `tcp` based on the route protocol; this feature is only available if you turn it on in routing release created_at: type: string format: date-time + description: The time with zone when the object was created updated_at: type: [string, "null"] format: date-time - metadata: - $ref: './Metadata.yaml' + description: The time with zone when the object was last updated links: type: object properties: - self: + destinations: $ref: './Link.yaml' - description: The URL to get this route destination + description: The URL to get the destinations for the route this destination belongs to route: $ref: './Link.yaml' description: The URL to get the route for this destination -description: A route destination is a specification for where traffic on a route should be directed. + description: Links to related resources +description: |- + A destination represents the relationship between a route and a resource that can serve traffic (for example, the `web` process of an application). + + When a route has destinations, that route will direct traffic to the processes represented by those destinations. + + If a destination is created with a port specified, the route will direct traffic to that port on the process. A destination with port 9000 and process type `api` means traffic will be directed to the `api` process running on container port 9000. + + Note that when using a custom port, the app process must be listening on the specified port for the mapping to work. Otherwise, visiting the route will result in a 404 error. + + If a destination does not specify a port, the default port depends on the app lifecycle type. For buildpack apps, traffic will be directed to port 8080. For Docker apps, the first port specified in the Dockerfile will be used. diff --git a/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationList.yaml b/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationList.yaml index 85794f07994..c00efe31cef 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationList.yaml @@ -1,9 +1,18 @@ type: object properties: - pagination: - $ref: './Pagination.yaml' destinations: type: array items: $ref: './RouteDestination.yaml' + description: List of destinations for the route + links: + type: object + properties: + self: + $ref: './Link.yaml' + description: The URL to get the destinations for this route + route: + $ref: './Link.yaml' + description: The URL to get the route these destinations belong to + description: Links to related resources description: A list of route destinations diff --git a/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationRequest.yaml b/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationRequest.yaml new file mode 100644 index 00000000000..5dd728c9bdf --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/RouteDestinationRequest.yaml @@ -0,0 +1,45 @@ +type: object +properties: + app: + type: object + properties: + guid: + type: string + format: uuid + description: Unique identifier for the app to route traffic to + process: + type: object + properties: + type: + type: string + description: Type of the process belonging to the app to route traffic to; defaults to `web` + description: The process of the app to route traffic to + required: + - guid + description: The app to route traffic to + port: + type: integer + minimum: 1024 + maximum: 65535 + description: Port on the destination process to route traffic to + weight: + type: + - integer + - 'null' + minimum: 1 + maximum: 100 + deprecated: true + description: 'Percentage of traffic which will be routed to this destination. **DEPRECATED:** this feature was only available via the experimental Service Mesh routing plane. It is no longer supported.' + protocol: + type: + - string + - 'null' + enum: + - http1 + - http2 + - tcp + - null + description: Protocol to use for this destination. Valid protocols are `http1` or `http2` if route protocol is `http`, `tcp` if route protocol is `tcp`. A `null` value will set it either `http1` or `tcp` based on the route protocol; this feature is only available if you turn it on in routing release +required: + - app +description: A destination to add to a route. Destinations without `process.type` specified will get process type `web` by default. diff --git a/docs/openapi/apis/cf/latest/components/schemas/RouteList.yaml b/docs/openapi/apis/cf/latest/components/schemas/RouteList.yaml index 6f691449e24..1f08895da7f 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/RouteList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/RouteList.yaml @@ -6,6 +6,7 @@ properties: type: array items: $ref: './Route.yaml' + description: List of routes included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/docs/openapi/apis/cf/latest/components/schemas/RouteOptions.yaml b/docs/openapi/apis/cf/latest/components/schemas/RouteOptions.yaml new file mode 100644 index 00000000000..534bb2fc40b --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/RouteOptions.yaml @@ -0,0 +1,19 @@ +type: object +properties: + loadbalancing: + type: string + enum: + - round-robin + - least-connection + - hash + description: The load-balancer associated with this route. Valid values are `round-robin`, `least-connection`, and `hash` + hash_header: + type: string + description: HTTP header name to hash for routing (e.g., `X-User-ID`, `Cookie`). Required when loadbalancing is `hash`. Cannot be set when loadbalancing is not `hash`. + hash_balance: + type: string + description: Weight factor for load balancing (1.1 - 10, or 0 for disabling balancing). Higher values consider load more. Optional when loadbalancing is `hash`. Cannot be set when loadbalancing is not `hash`. +description: |- + Options applied to the route. + + > **Note:** `hash`-based loadbalancing and the `hash_header` and `hash_balance` options are only available when the `hash_based_routing` feature flag is enabled. 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/components/schemas/SecurityGroup.yaml b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroup.yaml index 84ea72585ea..b4d63fd27ac 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroup.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroup.yaml @@ -5,68 +5,43 @@ allOf: name: type: string description: Name of the security group + rules: + type: array + items: + $ref: './SecurityGroupRule.yaml' + description: Rules that will be applied by this security group globally_enabled: type: object properties: running: type: boolean - description: Whether the security group is globally enabled for running apps + description: Specifies whether the group should be applied globally to all running applications staging: type: boolean - description: Whether the security group is globally enabled for staging apps - rules: - type: array - items: - type: object - properties: - protocol: - type: string - description: Protocol for the rule - destination: - type: string - description: Destination for the rule - ports: - type: string - description: Ports for the rule - type: - type: integer - description: Type for ICMP rules - code: - type: integer - description: Code for ICMP rules - description: - type: string - description: Description of the rule - description: Rules for the security group - running_spaces: - type: object - properties: - data: - type: array - items: - $ref: './Relationship.yaml' - description: Spaces where this security group is applied to running apps - staging_spaces: + description: Specifies whether the group should be applied globally to all staging applications + description: Object that controls if the group is applied globally to the lifecycle of all applications + relationships: type: object properties: - data: - type: array - items: - $ref: './Relationship.yaml' - description: Spaces where this security group is applied to staging apps + running_spaces: + $ref: './RelationshipToMany.yaml' + description: A relationship to the spaces where the security_group is applied to applications during runtime + staging_spaces: + $ref: './RelationshipToMany.yaml' + description: A relationship to the spaces where the security_group is applied to applications during staging + description: Relationships for the security group links: type: object properties: self: $ref: './Link.yaml' - running_spaces: - $ref: './Link.yaml' - staging_spaces: - $ref: './Link.yaml' - metadata: - $ref: './Metadata.yaml' + description: The URL of this security group + description: Links to related resources required: - name - globally_enabled - rules - - links \ No newline at end of file + - relationships + - links +description: |- + A collection of egress traffic rules that can be applied to the staging or running state of applications. diff --git a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupCreate.yaml b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupCreate.yaml index bd82d9c9204..39a8f0ddc0b 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupCreate.yaml @@ -2,41 +2,32 @@ type: object properties: name: type: string - description: Name of the security group + maxLength: 250 + description: Name of the security group; must be unique (case-sensitive) globally_enabled: type: object properties: running: type: boolean - description: Whether the security group is globally enabled for running apps + description: Specifies whether the group should be applied globally to all running applications staging: type: boolean - description: Whether the security group is globally enabled for staging apps + description: Specifies whether the group should be applied globally to all staging applications + description: Object that controls if the group is applied globally to the lifecycle of all applications rules: type: array items: - type: object - properties: - protocol: - type: string - description: Protocol for the rule - destination: - type: string - description: Destination for the rule - ports: - type: string - description: Ports for the rule - type: - type: integer - description: Type for ICMP rules - code: - type: integer - description: Code for ICMP rules - description: - type: [string, "null"] - description: Description of the rule - description: Rules for the security group - metadata: - $ref: './Metadata.yaml' + $ref: './SecurityGroupRule.yaml' + description: Rules that will be applied by this security group + relationships: + type: object + properties: + staging_spaces: + $ref: './RelationshipToMany.yaml' + description: A relationship to the spaces where the security group is applied to applications during staging + running_spaces: + $ref: './RelationshipToMany.yaml' + description: A relationship to the spaces where the security group is applied to applications during runtime + description: Relationships to the spaces the security group is applied to required: - - name \ No newline at end of file + - name diff --git a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupList.yaml b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupList.yaml index 4fd687540db..1d318721e02 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupList.yaml @@ -2,7 +2,9 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of security groups resources: type: array items: $ref: './SecurityGroup.yaml' + description: The list of security groups diff --git a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupRule.yaml b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupRule.yaml new file mode 100644 index 00000000000..43632ba41de --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupRule.yaml @@ -0,0 +1,46 @@ +type: object +properties: + protocol: + type: string + enum: + - tcp + - udp + - icmp + - icmpv6 + - all + description: Protocol type Valid values are `tcp`, `udp`, `icmp`, `icmpv6` or `all` + destination: + type: string + description: |- + The destination where the rule applies. Must be a singular valid CIDR, IP address, or IP address range unless `cc.security_groups.enable_comma_delimited_destinations` is enabled. Then, the destination can be a comma-delimited string of CIDRs, IP addresses, or IP address ranges. Octets within IPv4 destinations cannot contain leading zeros; eg. `10.0.0.0/24` is valid, but `010.00.000.0/24` is *not*. For `icmp`, only IPv4 addresses are allowed and for `icmpv6` only IPv6 addresses. + ports: + type: [string, "null"] + default: null + description: Ports that the rule applies to; can be a single port (`9000`), a comma-separated list (`9000,9001`), or a range (`9000-9200`) + type: + type: [integer, "null"] + minimum: -1 + maximum: 255 + default: null + description: |- + [Type](https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-types) required for ICMP protocol; valid values are between -1 and 255 (inclusive), where -1 allows all + code: + type: [integer, "null"] + minimum: -1 + maximum: 255 + default: null + description: |- + [Code](https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes) required for ICMP protocol; valid values are between -1 and 255 (inclusive), where -1 allows all + description: + type: [string, "null"] + default: null + description: A description for the rule; this field is limited to 16MB + log: + type: [boolean, "null"] + default: null + description: Enable logging for rule, only valid for tcp rules +required: + - protocol + - destination +description: |- + An egress traffic rule applied by a security group. diff --git a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupUpdate.yaml b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupUpdate.yaml index b281ff5d771..7e9fcde369f 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SecurityGroupUpdate.yaml @@ -2,39 +2,20 @@ type: object properties: name: type: string + maxLength: 250 description: Name of the security group globally_enabled: type: object properties: running: type: boolean - description: Whether the security group is globally enabled for running apps + description: Specifies whether the group should be applied globally to all running applications staging: type: boolean - description: Whether the security group is globally enabled for staging apps + description: Specifies whether the group should be applied globally to all staging applications + description: Object that controls if the group is applied globally to the lifecycle of all applications rules: type: array items: - type: object - properties: - protocol: - type: string - description: Protocol for the rule - destination: - type: string - description: Destination for the rule - ports: - type: string - description: Ports for the rule - type: - type: integer - description: Type for ICMP rules - code: - type: integer - description: Code for ICMP rules - description: - type: [string, "null"] - description: Description of the rule - description: Rules for the security group - metadata: - $ref: './Metadata.yaml' + $ref: './SecurityGroupRule.yaml' + description: Rules that will be applied by this security group diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceBroker.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceBroker.yaml index 2d5a4ecc00a..2712e5ac6fc 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceBroker.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceBroker.yaml @@ -1,4 +1,6 @@ type: object +description: |- + Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the service offerings and plans they offer. allOf: - $ref: './BaseSchema.yaml' - properties: @@ -11,22 +13,28 @@ allOf: description: URL of the service broker relationships: type: object + description: Relationships for the service broker properties: space: $ref: './RelationshipToOne.yaml' - description: Relationships for the service broker + description: The space the service broker is restricted to; omitted for globally available service brokers + metadata: + $ref: './Metadata.yaml' + description: Labels and annotations applied to the service broker links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - space: - $ref: './Link.yaml' + description: The URL of this service broker service_offerings: $ref: './Link.yaml' - metadata: - $ref: './Metadata.yaml' + description: The URL to list the service offerings provided by this service broker + space: + $ref: './Link.yaml' + description: The URL of the space the service broker is restricted to; only present for space-scoped service brokers required: - name - url - - links \ No newline at end of file + - links diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerAuthentication.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerAuthentication.yaml new file mode 100644 index 00000000000..6a5aed8ccdd --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerAuthentication.yaml @@ -0,0 +1,28 @@ +type: object +writeOnly: true +description: |- + Credentials used to authenticate against the service broker. + + Only `basic` authentication is currently supported; the credentials are write-only and are never returned by the API. +properties: + type: + type: string + enum: + - basic + description: Type of the authentication mechanisms that can be used. Valid value is `basic`. + credentials: + type: object + description: Credentials for given authentication type. + properties: + username: + type: string + description: The username with which to authenticate against the service broker. + password: + type: string + description: The password with which to authenticate against the service broker. + required: + - username + - password +required: + - type + - credentials diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerList.yaml index a1613eee430..5c445d16bfc 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceBrokerList.yaml @@ -1,4 +1,5 @@ type: object +description: A list of service brokers properties: pagination: $ref: './Pagination.yaml' @@ -6,3 +7,4 @@ properties: type: array items: $ref: './ServiceBroker.yaml' + description: List of service brokers diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingDetails.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingDetails.yaml new file mode 100644 index 00000000000..b22c57ebc60 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingDetails.yaml @@ -0,0 +1,18 @@ +type: object +properties: + credentials: + type: object + additionalProperties: true + description: The service broker provided credentials that an app or a developer uses to connect to the service instance + syslog_drain_url: + type: [string, "null"] + format: uri + description: URL to which logs for bound applications will be streamed; only present when the service broker returned one + volume_mounts: + type: array + items: + type: [string, object] + description: An array of configuration for mounting volumes when the app is started; only present when the service broker returned any +description: |- + The details of a service credential binding; it contains the connection details of the service instance that are made + available to an app or a developer. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingLastOperation.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingLastOperation.yaml index 259990adcbd..38aad0cef4f 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingLastOperation.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingLastOperation.yaml @@ -2,13 +2,16 @@ type: object properties: type: type: string - description: Type of the last operation + description: Either `create` or `delete` enum: - create - delete state: type: string - description: State of the last operation + description: |- + Either `initial`, `in progress`, `succeeded`, or `failed` + + > **Note:** The `initial` state indicates that no response from the service broker has been received yet. enum: - initial - in progress @@ -20,9 +23,9 @@ properties: created_at: type: string format: date-time - description: When the last operation was created + description: The time with zone when the operation started updated_at: type: string format: date-time - description: When the last operation was last updated -description: The last operation object for service credential bindings + description: The time with zone when the operation was last updated +description: The last operation object for service credential binding diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingList.yaml index 7ce081075ab..c724a93f75e 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceCredentialBindingList.yaml @@ -2,6 +2,7 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of service credential bindings resources: type: array items: @@ -13,6 +14,8 @@ properties: mapping: app: './AppCredentialBinding.yaml' key: './KeyCredentialBinding.yaml' + description: List of service credential bindings included: $ref: './IncludedResources.yaml' - description: Additional related resources included in the response when using the include parameter + description: Additional related resources included in the response when using the `include` parameter +description: A paginated list of service credential bindings diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceBrokerProvidedMetadata.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceBrokerProvidedMetadata.yaml new file mode 100644 index 00000000000..5e1a3246e98 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceBrokerProvidedMetadata.yaml @@ -0,0 +1,12 @@ +type: object +properties: + labels: + type: object + description: Broker-specified key-value pairs specifying attributes of Service Instances that do not directly imply behavior changes + attributes: + type: object + description: Broker-specific key-value pairs generated by the Broker that MAY imply behavior changes by the Platform +description: |- + The broker provided metadata object for service instances. + + Metadata provided by the service broker about this service instance; only shown when type is `managed`. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceLastOperation.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceLastOperation.yaml index 80ea6c8b5bb..3fb4c6c1464 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceLastOperation.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceLastOperation.yaml @@ -2,14 +2,17 @@ type: object properties: type: type: string - description: Type of the last operation + description: Either `create`, `update`, or `delete` enum: - create - update - delete state: type: string - description: State of the last operation + description: |- + Either `initial`, `in progress`, `succeeded`, or `failed` + + > **Note:** The `initial` state indicates that no response from the service broker has been received yet. enum: - initial - in progress @@ -21,9 +24,9 @@ properties: created_at: type: string format: date-time - description: When the last operation was created + description: The time with zone when the operation started updated_at: type: string format: date-time - description: When the last operation was last updated + description: The time with zone when the operation was last updated description: The last operation object for service instances diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceList.yaml index e1e99665339..02130195563 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceList.yaml @@ -2,6 +2,7 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of service instances resources: type: array items: @@ -12,4 +13,6 @@ properties: propertyName: type mapping: managed: './ManagedServiceInstance.yaml' - user-provided: './UserProvidedServiceInstance.yaml' \ No newline at end of file + user-provided: './UserProvidedServiceInstance.yaml' + description: List of service instances +description: A paginated list of service instances diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceMaintenanceInfo.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceMaintenanceInfo.yaml new file mode 100644 index 00000000000..be9af476632 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceInstanceMaintenanceInfo.yaml @@ -0,0 +1,12 @@ +type: object +properties: + version: + type: string + description: The current semantic version of this service instance; comparing this version with the version of the Service Plan can be used to determine whether or not this service instance is up to date with the Service Plan + description: + type: [string, "null"] + description: A textual explanation associated with this version +description: |- + The maintenance info object for service instances. + + Information about the version of this service instance; only shown when type is `managed`. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceOffering.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceOffering.yaml index c3ceed7fb98..8b5a66d4d4f 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceOffering.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceOffering.yaml @@ -1,22 +1,98 @@ type: object +description: |- + Service offerings represent the services offered by service brokers. + A service broker will have one or more service offerings. + A service offering will have one or more service plans. + Service offerings and service plans are created and updated when a service broker is registered or updated. allOf: - $ref: './BaseSchema.yaml' - properties: - service_broker_guid: + name: type: string - service_broker_name: + description: Name of the service offering + description: type: string + description: Description of the service offering + available: + type: boolean + description: Whether or not the service offering is available + tags: + type: array + items: + type: string + description: Descriptive tags for the service offering + requires: + type: array + items: + type: string + enum: + - syslog_drain + - route_forwarding + - volume_mount + description: A list of permissions that the user would have to give the service, if they provision it; the only permissions currently supported are `syslog_drain`, `route_forwarding` and `volume_mount` + shareable: + type: boolean + description: Whether or not service Instances of this service offering can be shared across organizations and spaces + documentation_url: + type: [string, "null"] + description: Url that points to a documentation page for the service offering, if provided by the service broker as part of the metadata field + broker_catalog: + type: object + description: This object contains information obtained from the service broker Catalog + properties: + id: + type: string + description: The identifier that the service broker provided for this service offering + metadata: + type: object + additionalProperties: true + description: Additional information provided by the service broker as specified by [OSBAPI](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md#service-metadata-fields) + features: + type: object + description: Features supported by this service offering + properties: + plan_updateable: + type: boolean + description: Whether the service offering supports upgrade/downgrade for service plans by default; service plans can override this field + bindable: + type: boolean + description: Specifies whether service Instances of the service can be bound to applications + instances_retrievable: + type: boolean + description: Specifies whether the Fetching a service instance endpoint is supported for all service plans + bindings_retrievable: + type: boolean + description: Specifies whether the Fetching a service binding endpoint is supported for all service plans + allow_context_updates: + type: boolean + description: Specifies whether service instance updates relating only to context are propagated to the service broker + relationships: + type: object + description: Relationships for the service offering + properties: + service_broker: + $ref: './RelationshipToOne.yaml' + description: The service broker that provides this service offering metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service offering links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL to get this service offering + description: The URL of this service offering service_plans: $ref: './Link.yaml' - description: The URL to get the service plans for this offering + description: The URL to list the service plans of this service offering service_broker: $ref: './Link.yaml' - description: The URL to get the service broker for this offering \ No newline at end of file + description: The URL of the service broker that provides this service offering + required: + - name + - description + - available + - broker_catalog + - relationships + - links diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceOfferingList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceOfferingList.yaml index 681d7470287..3eb16594c9b 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceOfferingList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceOfferingList.yaml @@ -1,4 +1,5 @@ type: object +description: A list of service offerings properties: pagination: $ref: './Pagination.yaml' @@ -6,3 +7,7 @@ properties: type: array items: $ref: './ServiceOffering.yaml' + description: List of service offerings + included: + $ref: './IncludedResources.yaml' + description: Additional related resources included in the response when using the fields parameter diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServicePlan.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServicePlan.yaml index bb034500126..b0ec8de923a 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServicePlan.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServicePlan.yaml @@ -1,25 +1,157 @@ type: object +description: |- + Service plans represent the service plans offered by a service offering. + A service offering will have one or more service plans. + Service offerings and service plans are created and updated when a service broker is registered or updated. allOf: - $ref: './BaseSchema.yaml' - properties: - service_offering_guid: + name: type: string - service_offering_name: + description: Name of the service plan + visibility_type: type: string + enum: + - public + - admin + - organization + - space + description: Denotes the visibility of the plan; can be `public`, `admin`, `organization`, `space`, see [_list of visibility types_](#list-of-visibility-types) + available: + type: boolean + description: Whether or not the service plan is available + free: + type: boolean + description: Whether or not the service plan is free of charge + costs: + type: array + description: The cost of the service plan as obtained from the service broker catalog + items: + type: object + description: The service plan cost + properties: + amount: + type: number + format: float + description: Pricing amount + currency: + type: string + description: Currency code for the pricing amount, e.g. USD, GBP + unit: + type: string + description: Display name for type of cost, e.g. Monthly, Hourly, Request, GB + description: + type: string + description: Description of the service plan + maintenance_info: + type: object + description: Information about the version of this service plan + properties: + version: + type: string + description: The current semantic version of the service plan; comparing this version with that of a service instance can be used to determine whether or not the service instance is up to date with this service plan + description: + type: string + description: A textual explanation associated with this version + broker_catalog: + type: object + description: This object contains information obtained from the service broker catalog + properties: + id: + type: string + description: The identifier that the service broker provided for this service plan + metadata: + type: object + additionalProperties: true + description: Additional information provided by the service broker as specified by [OSBAPI](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md#plan-metadata-fields) + maximum_polling_duration: + type: [integer, "null"] + description: The maximum number of seconds that Cloud Foundry will wait for an asynchronous service broker operation + features: + type: object + description: Features supported by this service plan + properties: + plan_updateable: + type: boolean + description: Whether the service plan supports upgrade/downgrade for service plans; when the catalog does not specify a value, it is inherited from the service offering + bindable: + type: boolean + description: Specifies whether service instances of the service can be bound to applications + schemas: + type: object + description: Schema definitions for service instances and service bindings for the service plan + properties: + service_instance: + type: object + description: Schema definitions for service instances of this service plan + properties: + create: + type: object + description: Schema definition for service instance creation + properties: + parameters: + type: object + additionalProperties: true + description: The schema definition for the input parameters; each input parameter is expressed as a property within a JSON object + update: + type: object + description: Schema definition for service instance update + properties: + parameters: + type: object + additionalProperties: true + description: The schema definition for the input parameters; each input parameter is expressed as a property within a JSON object + service_binding: + type: object + description: Schema definitions for service bindings of this service plan + properties: + create: + type: object + description: Schema definition for service Binding creation + properties: + parameters: + type: object + additionalProperties: true + description: The schema definition for the input parameters; each input parameter is expressed as a property within a JSON object + relationships: + type: object + description: Relationships for the service plan + properties: + service_offering: + $ref: './RelationshipToOne.yaml' + description: The service offering that this service plan relates to + space: + $ref: './RelationshipToOne.yaml' + description: The space of the service broker, if this service plan is from a space-scoped service broker metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service plan links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL to get this service plan + description: The URL of this service plan service_offering: $ref: './Link.yaml' - description: The URL to get the service offering for this plan + description: The URL of the service offering that this service plan relates to visibility: $ref: './Link.yaml' - description: The URL to get the visibility for this plan + description: The URL of the visibility of this service plan + space: + $ref: './Link.yaml' + description: The URL of the space of the service broker; only present for service plans from space-scoped service brokers included: $ref: './IncludedResources.yaml' - description: Additional related resources included in the response when using the include parameter \ No newline at end of file + description: Additional related resources included in the response when using the include parameter + required: + - name + - visibility_type + - available + - free + - description + - broker_catalog + - schemas + - relationships + - links diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServicePlanList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServicePlanList.yaml index 5a6663cd091..51df1a37e01 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServicePlanList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServicePlanList.yaml @@ -1,4 +1,5 @@ type: object +description: A list of service plans properties: pagination: $ref: './Pagination.yaml' @@ -6,6 +7,7 @@ properties: type: array items: $ref: './ServicePlan.yaml' + description: List of service plans included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServicePlanVisibility.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServicePlanVisibility.yaml index 9e426b2b319..8f60f4116d4 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServicePlanVisibility.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServicePlanVisibility.yaml @@ -1,25 +1,38 @@ type: object +description: Service plan visibility is used to manage whether a role has access to a given service plan and its service offering. properties: type: type: string - description: Type of visibility enum: - public - admin - organization - space + description: Denotes the visibility of the plan; can be `public`, `admin`, `organization`, `space`, see [_list of visibility types_](#list-of-visibility-types) + space: + type: object + description: The space whose members can access the plan; present if `type` is `space` + properties: + guid: + type: string + format: uuid + description: Unique identifier for the space whose members can access the plan; present if `type` is `space` + name: + type: string + description: Name of the space whose members can access the plan; present if `type` is `space` organizations: type: array + description: List of organizations whose members can access the plan; present if `type` is `organization` items: type: object + description: The organization visibility object properties: guid: type: string format: uuid - description: Organization GUID + description: Unique identifier for the organization where the plan is available name: type: string - description: Organization name - description: Organizations that have visibility to this service plan + description: Name of the organization where the plan is available required: - type diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBinding.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBinding.yaml index 03fbeae88f1..304aab68f6c 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBinding.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBinding.yaml @@ -5,31 +5,46 @@ allOf: route_service_url: type: [string, "null"] format: uri - description: URL for the route service + description: The URL for the route service last_operation: - $ref: './ServiceCredentialBindingLastOperation.yaml' + oneOf: + - $ref: './ServiceRouteBindingLastOperation.yaml' + - type: "null" + description: The last operation of this binding relationships: type: object properties: route: $ref: './RelationshipToOne.yaml' + description: The route that the service instance is bound to service_instance: $ref: './RelationshipToOne.yaml' + description: The service instance that the route is bound to description: Relationships for the service route binding links: type: object properties: self: $ref: './Link.yaml' + description: Link to this service route binding route: $ref: './Link.yaml' + description: Link to the route that the service instance is bound to service_instance: $ref: './Link.yaml' + description: Link to the service instance that the route is bound to + parameters: + $ref: './Link.yaml' + description: Link to the parameters that this binding was created with; only present for bindings to managed service instances + description: Links to related resources metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service route binding included: $ref: './IncludedResources.yaml' - description: Additional related resources included in the response when using the include parameter + description: Additional related resources included in the response when using the `include` parameter required: - - relationships - - links \ No newline at end of file + - relationships + - links +description: |- + A service route binding; a relation between a [service instance](#service-instances) and a [route](#routes). diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingCreate.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingCreate.yaml index 5f518525951..3058cff8fca 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingCreate.yaml @@ -15,8 +15,11 @@ properties: description: Relationships for the service route binding parameters: type: object - description: A JSON object that is passed to the service broker + additionalProperties: true + description: A JSON object that is passed to the service broker; only valid for managed service instances metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service route binding; only valid for managed service instances required: - - relationships \ No newline at end of file + - relationships +description: A request to create a service route binding diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingLastOperation.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingLastOperation.yaml new file mode 100644 index 00000000000..5263cd69372 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingLastOperation.yaml @@ -0,0 +1,31 @@ +type: object +properties: + type: + type: string + description: Either `create` or `delete` + enum: + - create + - delete + state: + type: string + description: |- + Either `initial`, `in progress`, `succeeded`, or `failed` + + > **Note:** The `initial` state indicates that no response from the service broker has been received yet. + enum: + - initial + - in progress + - succeeded + - failed + description: + type: [string, "null"] + description: A textual explanation associated with this state + created_at: + type: string + format: date-time + description: The time with zone when the operation started + updated_at: + type: string + format: date-time + description: The time with zone when the operation was last updated +description: The last operation object for service route binding diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingList.yaml index dbe3c61e35a..b3d93d3ad6a 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceRouteBindingList.yaml @@ -2,10 +2,13 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of service route bindings resources: type: array items: $ref: './ServiceRouteBinding.yaml' + description: List of service route bindings included: $ref: './IncludedResources.yaml' - description: Additional related resources included in the response when using the include parameter + description: Additional related resources included in the response when using the `include` parameter +description: A paginated list of service route bindings diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEvent.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEvent.yaml index 17e123c290d..93c1e973e06 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEvent.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEvent.yaml @@ -2,9 +2,89 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the event + created_at: + type: string + format: date-time + description: The time with zone when the event occurred + updated_at: + type: string + format: date-time + description: Identical to `created_at` (events are created, never updated) + state: + type: [string, "null"] + description: Current state of the service that this event pertains to, if applicable + space: + type: object + description: The space that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the space that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the space that this event pertains to, if applicable + organization: + type: object + description: The organization that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the org that this event pertains to, if applicable + service_instance: + type: object + description: The service instance that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the service instance that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the service instance that this event pertains to, if applicable + type: + type: [string, "null"] + description: Type of the service instance that this event pertains to, if applicable; valid values are `managed_service_instance` and `user_provided_service_instance` + service_plan: + type: object + description: The service plan that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the service plan that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the service plan that this event pertains to, if applicable + service_offering: + type: object + description: The service offering that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the service offering that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the service offering that this event pertains to, if applicable + service_broker: + type: object + description: The service broker that this event pertains to + properties: + guid: + type: [string, "null"] + description: Unique identifier of the service broker that this event pertains to, if applicable + name: + type: [string, "null"] + description: Name of the service broker that this event pertains to, if applicable links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL to get this service usage event \ No newline at end of file + description: The URL to get this service usage event +description: |- + Service usage events are a record of changes in the usage of services. For example, service usage events are recorded when a service instance is created, updated, and deleted. They may contain information about the service instance in question and the associated space, service broker, and service offering. + + Usage events are typically used by billing and chargeback applications. diff --git a/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEventList.yaml b/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEventList.yaml index 2dd8d9dc3fe..c16a5875115 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEventList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/ServiceUsageEventList.yaml @@ -2,7 +2,9 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of service usage events resources: type: array items: $ref: './ServiceUsageEvent.yaml' + description: The list of service usage events diff --git a/docs/openapi/apis/cf/latest/components/schemas/Sidecar.yaml b/docs/openapi/apis/cf/latest/components/schemas/Sidecar.yaml index 7b4211671e5..b97c6bc2668 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Sidecar.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Sidecar.yaml @@ -2,43 +2,49 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the sidecar name: type: string - description: Name of the sidecar + description: Human-readable name for the sidecar command: type: string - description: Command to run for the sidecar + description: The command used to start the sidecar process_types: type: array items: type: string - description: Process types that the sidecar applies to + description: A list of process types the sidecar applies to memory_in_mb: type: [integer, "null"] - description: Memory limit for the sidecar in MB + description: Reserved memory for sidecar origin: - type: [string, "null"] - description: Origin of the sidecar + type: string + description: Specifies whether the sidecar was created by the user or via the buildpack enum: - user - buildpack relationships: type: object + description: Relationships to other resources properties: app: $ref: './RelationshipToOne.yaml' - description: Relationships for the sidecar - links: - type: object - properties: - self: - $ref: './Link.yaml' - app: - $ref: './Link.yaml' - metadata: - $ref: './Metadata.yaml' + description: The app the sidecar is associated with + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated required: - - name - - command - - process_types - - relationships \ No newline at end of file + - name + - command + - process_types + - relationships +description: |- + Sidecars are additional operating system processes that are run in the same container as a process. diff --git a/docs/openapi/apis/cf/latest/components/schemas/SidecarCreate.yaml b/docs/openapi/apis/cf/latest/components/schemas/SidecarCreate.yaml index 73f3db072d4..6b178db8e58 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SidecarCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SidecarCreate.yaml @@ -2,15 +2,21 @@ type: object properties: name: type: string - description: Name of the sidecar + description: Human-readable name for the sidecar command: type: string - description: Command to run for the sidecar + description: The command used to start the sidecar process_types: type: array items: type: string - description: Process types that the sidecar applies to + description: A list of process types the sidecar applies to memory_in_mb: type: [integer, "null"] - description: Memory limit for the sidecar in MB + description: Reserved memory for sidecar +required: + - name + - command + - process_types +description: |- + Request schema for creating a sidecar associated with an app. diff --git a/docs/openapi/apis/cf/latest/components/schemas/SidecarList.yaml b/docs/openapi/apis/cf/latest/components/schemas/SidecarList.yaml index 49efa5d66a8..2ddc8812126 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SidecarList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SidecarList.yaml @@ -2,7 +2,11 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of sidecars resources: type: array items: $ref: './Sidecar.yaml' + description: The list of sidecars +description: |- + A paginated list of sidecars. diff --git a/docs/openapi/apis/cf/latest/components/schemas/Space.yaml b/docs/openapi/apis/cf/latest/components/schemas/Space.yaml index e9dfc682490..7b4ab2d21c0 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Space.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Space.yaml @@ -5,31 +5,46 @@ allOf: name: type: string description: Name of the space + suspended: + type: boolean + description: Whether a space is suspended or not; non-admins and non-org-managers will be blocked from creating, updating, or deleting resources in a suspended space relationships: type: object + description: Relationships for the space properties: organization: $ref: './RelationshipToOne.yaml' + description: The organization the space is contained in quota: $ref: './RelationshipToOne.yaml' - description: Relationships for the space + description: The space quota applied to the space links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' + description: The URL of this space organization: $ref: './Link.yaml' + description: The URL of the organization the space is contained in features: $ref: './Link.yaml' + description: The URL to list the features of this space + quota: + $ref: './Link.yaml' + description: The URL of the space quota applied to the space; only present when a space quota is applied apply_manifest: $ref: './Link.yaml' + description: The URL to apply a manifest to this space metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the space included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter required: - name + - suspended - relationships - - links \ No newline at end of file + - links diff --git a/docs/openapi/apis/cf/latest/components/schemas/SpaceFeature.yaml b/docs/openapi/apis/cf/latest/components/schemas/SpaceFeature.yaml index 28375c576bb..d51a200ce34 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SpaceFeature.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SpaceFeature.yaml @@ -1,8 +1,21 @@ type: object +description: |- + Space features are used to manage whether optional capabilities are enabled for a given space. + + Currently, the only space feature is SSH (`ssh`), which controls whether applications in the space may be accessed via SSH. + + > **Note:** SSH must also be [enabled globally](https://docs.cloudfoundry.org/running/config-ssh.html) and on the [app](#supported-app-features). properties: name: type: string + description: Name of the space feature description: - type: [string, "null"] + type: string + description: Description of the space feature enabled: type: boolean + description: Denotes whether or not the space feature is enabled +required: + - name + - description + - enabled diff --git a/docs/openapi/apis/cf/latest/components/schemas/SpaceFeatureList.yaml b/docs/openapi/apis/cf/latest/components/schemas/SpaceFeatureList.yaml new file mode 100644 index 00000000000..ba313505858 --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/SpaceFeatureList.yaml @@ -0,0 +1,10 @@ +type: object +description: The list of features for a space; this list is not paginated +properties: + resources: + type: array + items: + $ref: './SpaceFeature.yaml' + description: List of space features +required: + - resources diff --git a/docs/openapi/apis/cf/latest/components/schemas/SpaceList.yaml b/docs/openapi/apis/cf/latest/components/schemas/SpaceList.yaml index af670208f16..79f92285563 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SpaceList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SpaceList.yaml @@ -2,10 +2,12 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of spaces resources: type: array items: $ref: './Space.yaml' + description: List of spaces included: $ref: './IncludedResources.yaml' description: Additional related resources included in the response when using the include parameter diff --git a/docs/openapi/apis/cf/latest/components/schemas/SpaceQuota.yaml b/docs/openapi/apis/cf/latest/components/schemas/SpaceQuota.yaml index f51caf4ca63..6cd61f88083 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SpaceQuota.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SpaceQuota.yaml @@ -2,72 +2,91 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the space quota + created_at: + type: string + format: date-time + description: The time with zone when the space quota was created + updated_at: + type: string + format: date-time + description: The time with zone when the space quota was last updated name: type: string - description: Name of the space quota + description: Name of the quota apps: type: object + description: Quotas that affect applications and application sub-resources properties: total_memory_in_mb: type: [integer, 'null'] - description: Total memory allowed for all apps in MB + description: Total memory allowed for all the started processes and running tasks in a space; `null` means infinite per_process_memory_in_mb: type: [integer, 'null'] - description: Maximum memory per process in MB + description: Maximum memory for a single process or task; `null` means infinite log_rate_limit_in_bytes_per_second: type: [integer, 'null'] - description: Log rate limit in bytes per second + description: Total log rate limit allowed for all the started processes and running tasks in an organization; `null` means infinite total_instances: type: [integer, 'null'] - description: Total number of app instances allowed + description: Total instances of all the started processes allowed in a space; `null` means infinite per_app_tasks: type: [integer, 'null'] - description: Maximum number of tasks per app - description: App limits for the space quota + description: Maximum number of running tasks in a space; `null` means infinite services: type: object + description: Quotas that affect services properties: paid_services_allowed: type: boolean - description: Whether paid services are allowed + description: Specifies whether instances of paid service plans can be created total_service_instances: type: [integer, 'null'] - description: Total number of service instances allowed + description: Total number of service instances allowed in a space; `null` means infinite total_service_keys: type: [integer, 'null'] - description: Total number of service keys allowed - description: Service limits for the space quota + description: Total number of service keys allowed in a space; `null` means infinite routes: type: object + description: Quotas that affect routes properties: total_routes: type: [integer, 'null'] - description: Total number of routes allowed + description: Total number of routes allowed in a space; `null` means infinite total_reserved_ports: type: [integer, 'null'] - description: Total number of reserved ports allowed - description: Route limits for the space quota + description: Total number of ports that are reservable by routes in a space; `null` means infinite relationships: type: object + description: Relationships for the space quota properties: organization: $ref: './RelationshipToOne.yaml' + description: A relationship to the organization where the quota belongs spaces: $ref: './RelationshipToMany.yaml' - description: Relationships for the space quota + description: A relationship to the spaces where the quota is applied links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' + description: The URL to get this space quota organization: $ref: './Link.yaml' - metadata: - $ref: './Metadata.yaml' + description: The URL to get the organization where the quota belongs required: - name - apps - services - routes - relationships - - links \ No newline at end of file + - links +description: | + Space quotas are named sets of quotas. Space quota names are unique within an organization. + + Only one space quota may be applied to a given space at any given time. Space quotas cannot be used to bypass organization quotas; when the organization's quota and the space's quota specify different values for a given resource, the more restrictive of the two is used. diff --git a/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaList.yaml b/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaList.yaml index d8849c42e2d..22f1996bf59 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaList.yaml @@ -4,5 +4,7 @@ properties: $ref: './Pagination.yaml' resources: type: array + description: List of space quotas items: $ref: './SpaceQuota.yaml' +description: A paginated list of space quotas diff --git a/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaUpdate.yaml b/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaUpdate.yaml index 9cb34fe6b46..1e302a88dd1 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/SpaceQuotaUpdate.yaml @@ -1,49 +1,49 @@ type: object properties: name: - type: [string, "null"] - description: Name of the space quota + type: string + description: Name of the quota apps: type: object + description: Quotas that affect applications and application sub-resources properties: total_memory_in_mb: type: [integer, "null"] - description: Total memory allowed for all apps in MB + description: Total memory of all the started processes and running tasks in a space per_process_memory_in_mb: type: [integer, "null"] - description: Maximum memory per process in MB + description: Maximum memory for a single process or task log_rate_limit_in_bytes_per_second: type: [integer, "null"] - description: Log rate limit in bytes per second + description: Total log rate limit allowed for all the started processes and running tasks in an organization total_instances: type: [integer, "null"] - description: Total number of app instances allowed + description: Total instances of all the started processes in a space per_app_tasks: type: [integer, "null"] - description: Maximum number of tasks per app - description: App limits for the space quota + description: Maximum number of running tasks in a space services: type: object + description: Quotas that affect services properties: paid_services_allowed: type: boolean - description: Whether paid services are allowed + description: If instances of paid service plans can be created total_service_instances: type: [integer, "null"] - description: Total number of service instances allowed + description: Total number of service instances in a space total_service_keys: type: [integer, "null"] - description: Total number of service keys allowed - description: Service limits for the space quota + description: Total number of service keys in a space routes: type: object + description: Quotas that affect routes properties: total_routes: type: [integer, "null"] - description: Total number of routes allowed + description: Total number of routes that a space can have total_reserved_ports: type: [integer, "null"] - description: Total number of reserved ports allowed - description: Route limits for the space quota - metadata: - $ref: ./Metadata.yaml + description: Total number of ports that all routes in a space can reserve +description: | + Only the parameters specified in the request body are updated; any unspecified parameters retain their existing values. diff --git a/docs/openapi/apis/cf/latest/components/schemas/Stack.yaml b/docs/openapi/apis/cf/latest/components/schemas/Stack.yaml index a26a0c1bd12..18f0d835645 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Stack.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Stack.yaml @@ -4,27 +4,43 @@ allOf: - properties: name: type: string - description: Name of the stack + description: The name of the stack description: type: [string, "null"] - description: Description of the stack + description: The description of the stack + state: + type: string + enum: + - ACTIVE + - RESTRICTED + - DEPRECATED + - DISABLED + description: 'The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`' + state_reason: + type: [string, "null"] + description: Optional plain text describing the stack state change build_rootfs_image: type: string - description: The filesystem root image for building + description: The name of the stack image associated with staging/building Apps. If a stack does not have unique images, this will be the same as the stack name. run_rootfs_image: type: string - description: The filesystem root image for running + description: The name of the stack image associated with running Apps + Tasks. If a stack does not have unique images, this will be the same as the stack name. default: type: boolean - description: Whether this is the default stack + description: Whether the stack is configured to be the default stack for new applications. + metadata: + $ref: './Metadata.yaml' + description: Labels and annotations applied to the stack links: type: object properties: self: $ref: './Link.yaml' - metadata: - $ref: './Metadata.yaml' + description: The URL of this stack + description: Links to related resources required: - name - description - links +description: |- + The base operating system and file system that an application will execute in. diff --git a/docs/openapi/apis/cf/latest/components/schemas/StackList.yaml b/docs/openapi/apis/cf/latest/components/schemas/StackList.yaml index f6e95370b95..49a476bba4f 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/StackList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/StackList.yaml @@ -2,7 +2,9 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of stacks resources: type: array items: $ref: './Stack.yaml' + description: The list of stacks diff --git a/docs/openapi/apis/cf/latest/components/schemas/Task.yaml b/docs/openapi/apis/cf/latest/components/schemas/Task.yaml index 7e6d97cc06d..69a337f3d96 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/Task.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/Task.yaml @@ -2,36 +2,87 @@ type: object allOf: - $ref: './BaseSchema.yaml' - properties: + guid: + type: string + format: uuid + description: Unique identifier for the task + created_at: + type: string + format: date-time + description: The time with zone when the object was created + updated_at: + type: string + format: date-time + description: The time with zone when the object was last updated + sequence_id: + type: integer + description: User-facing id of the task; this number is unique for every task associated with a given app name: type: string + description: Name of the task command: type: string + description: Command that will be executed; this field may be excluded based on a user's role + user: + type: [string, "null"] + description: The OS user used to run the task in the runtime state: type: string + description: State of the task. Possible states are `PENDING`, `RUNNING`, `SUCCEEDED`, `CANCELING`, and `FAILED` enum: - PENDING - RUNNING - SUCCEEDED - - FAILED - CANCELING - sequence_id: - type: integer + - FAILED memory_in_mb: type: [integer, "null"] + description: Amount of memory to allocate for the task in MB disk_in_mb: type: [integer, "null"] - droplet_guid: - type: string + description: Amount of disk to allocate for the task in MB + log_rate_limit_in_bytes_per_second: + type: [integer, "null"] + description: Amount of log rate to allocate for the task in bytes result: type: object + description: Results from the task properties: failure_reason: type: [string, "null"] + description: Null if the task succeeds, contains the error message if it fails + droplet_guid: + type: string + format: uuid + description: The guid of the droplet that will be used to run the command + relationships: + type: object + description: Relationships to other resources + properties: + app: + $ref: './RelationshipToOne.yaml' + description: The app the task belongs to metadata: $ref: './Metadata.yaml' + description: |- + `labels`: Labels applied to the task + + `annotations`: Annotations applied to the task links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' -description: A task is a one-off process that can be run in the Cloud Foundry environment. + description: A link to the task itself + app: + $ref: './Link.yaml' + description: A link to the app the task belongs to + cancel: + $ref: './Link.yaml' + description: A link to cancel the task; the link must be followed with a `POST` request + droplet: + $ref: './Link.yaml' + description: A link to the droplet the task is running +description: |- + Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources. diff --git a/docs/openapi/apis/cf/latest/components/schemas/TaskList.yaml b/docs/openapi/apis/cf/latest/components/schemas/TaskList.yaml index c4dd3ab148e..1c4ef920023 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/TaskList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/TaskList.yaml @@ -2,7 +2,11 @@ type: object properties: pagination: $ref: './Pagination.yaml' + description: Pagination information for the list of tasks resources: type: array items: $ref: './Task.yaml' + description: The list of tasks +description: |- + A paginated list of tasks. diff --git a/docs/openapi/apis/cf/latest/components/schemas/User.yaml b/docs/openapi/apis/cf/latest/components/schemas/User.yaml index 6252481d2d2..78a1756b72a 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/User.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/User.yaml @@ -6,25 +6,30 @@ properties: created_at: type: string format: date-time - description: The ISO8601 compatible date and time when resource was created + description: The time with zone when the object was created updated_at: type: string format: date-time - description: The ISO8601 compatible date and time when resource was last updated + description: The time with zone when the object was last updated username: type: [string, "null"] - description: The username of the user + description: The name registered in UAA; will be `null` for UAA clients and non-UAA users presentation_name: type: string - description: The presentation name of the user + description: The name displayed for the user; for UAA users, this is the same as the username. For UAA clients, this is the UAA client ID origin: type: [string, "null"] - description: The origin of the user + description: The identity provider for the UAA user; will be `null` for UAA clients metadata: $ref: './Metadata.yaml' + description: Labels applied to and annotations added to the user links: type: object + description: Links to related resources properties: self: $ref: './Link.yaml' - description: The URL to get this user \ No newline at end of file + description: The URL to get this user +description: | + The user resource is used to manage access to organizations, spaces, and other resources within Cloud Foundry. + Cloud Controller users "shadow" a corresponding user or client in UAA; the user's guid should match either a UAA user id or a UAA client id. diff --git a/docs/openapi/apis/cf/latest/components/schemas/UserCreate.yaml b/docs/openapi/apis/cf/latest/components/schemas/UserCreate.yaml index d4005ee72d2..f125c52fa83 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/UserCreate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/UserCreate.yaml @@ -1,20 +1,32 @@ -anyOf: - - type: object +oneOf: + - title: By guid + type: object + required: + - guid + additionalProperties: false properties: guid: type: string - description: Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user's GUID; in the case of UAA clients, this will match the UAA client ID + description: Unique identifier for the user. For UAA users this will match the UAA user ID; in the case of UAA clients, this will match the UAA client ID metadata: $ref: './Metadata.yaml' - required: [guid] - - type: object + description: Labels applied to and annotations added to the user + - title: By username and origin + type: object + required: + - username + - origin + additionalProperties: false properties: username: - type: [string, "null"] - description: Username of the user to be created. This can only be provided together with origin + type: string + description: Username of the user to be created. This can only be provided together with `origin`. origin: - type: [string, "null"] - description: Origin of the user to be created. This can only be provided together with username and cannot be uaa + type: string + description: Origin of the user to be created. This can only be provided together with `username` and cannot be `uaa`. metadata: $ref: './Metadata.yaml' - required: [username, origin] + description: Labels applied to and annotations added to the user +description: | + A user is created either by `guid` (the UAA user id or UAA client id) or by `username` and `origin`. + Creating a user by guid is only permitted by admins. diff --git a/docs/openapi/apis/cf/latest/components/schemas/UserList.yaml b/docs/openapi/apis/cf/latest/components/schemas/UserList.yaml index 5ccb83d62de..090efcfb6c1 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/UserList.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/UserList.yaml @@ -4,5 +4,7 @@ properties: $ref: './Pagination.yaml' resources: type: array + description: List of users items: $ref: './User.yaml' +description: A paginated list of users diff --git a/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstance.yaml b/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstance.yaml index 59d2c135dd4..a0d266e9eb0 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstance.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstance.yaml @@ -6,7 +6,7 @@ allOf: type: string enum: - user-provided - description: Type of service instance + description: Either `managed` or `user-provided` name: type: string description: Name of the service instance @@ -14,38 +14,51 @@ allOf: type: array items: type: string - description: Tags for the service instance + description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env syslog_drain_url: type: [string, "null"] format: uri - description: URL for syslog drain + description: URL to which logs for bound applications will be streamed; only shown when type is `user-provided` route_service_url: type: [string, "null"] format: uri - description: URL for route service + description: URL to which requests for bound routes will be forwarded; only shown when type is `user-provided` + last_operation: + $ref: './ServiceInstanceLastOperation.yaml' + description: The last operation of this service instance relationships: type: object properties: space: $ref: './RelationshipToOne.yaml' + description: The space the service instance is contained in description: Relationships for the service instance links: type: object properties: self: $ref: './Link.yaml' + description: Link to this service instance space: $ref: './Link.yaml' + description: Link to the space the service instance is contained in + credentials: + $ref: './Link.yaml' + description: Link to the credentials of this user-provided service instance service_credential_bindings: $ref: './Link.yaml' + description: Link to the service credential bindings for this service instance service_route_bindings: $ref: './Link.yaml' - credentials: - $ref: './Link.yaml' + description: Link to the service route bindings for this service instance + description: Links to related resources metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service instance required: - type - name - relationships - - links \ No newline at end of file + - links +description: |- + A user-provided service instance describes an instance of an offering that is not registered with CF. diff --git a/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceCreate.yaml b/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceCreate.yaml new file mode 100644 index 00000000000..b7d551677bd --- /dev/null +++ b/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceCreate.yaml @@ -0,0 +1,46 @@ +type: object +required: + - type + - name + - relationships +properties: + type: + type: string + enum: + - user-provided + description: Must be `user-provided` + name: + type: string + description: Name of the service instance; must be unique within the space (case-sensitive) + tags: + type: array + items: + type: string + description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env + credentials: + type: object + description: A JSON object that is made available to apps bound to this service instance + syslog_drain_url: + type: string + format: uri + description: URL to which logs for bound applications will be streamed + route_service_url: + type: string + format: uri + description: URL to which requests for bound routes will be forwarded; must use the `https` protocol + relationships: + type: object + required: + - space + properties: + space: + $ref: './RelationshipToOne.yaml' + description: The space in which to create the service instance + description: Relationships for the service instance + metadata: + $ref: './Metadata.yaml' + description: Labels and annotations applied to the service instance +description: |- + Parameters for creating a user-provided service instance. + + User provided service instances do not require interactions with service brokers. diff --git a/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceUpdate.yaml b/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceUpdate.yaml index 9f980d74a55..f9360d0e3ee 100644 --- a/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceUpdate.yaml +++ b/docs/openapi/apis/cf/latest/components/schemas/UserProvidedServiceInstanceUpdate.yaml @@ -7,18 +7,19 @@ properties: type: array items: type: string - description: Tags for the service instance + description: Tags are used by apps to identify service instances; they are shown in the app VCAP_SERVICES env credentials: type: object - description: Service credentials + description: A JSON object that is made available to apps bound to this service instance syslog_drain_url: type: [string, "null"] format: uri - description: URL for syslog drain + description: URL to which logs for bound applications will be streamed route_service_url: - type: string + type: [string, "null"] format: uri - description: URL for route service + description: URL to which requests for bound routes will be forwarded; must use the `https` protocol metadata: $ref: './Metadata.yaml' + description: Labels and annotations applied to the service_instance description: Schema for updating a user-provided service instance diff --git a/docs/openapi/apis/cf/latest/openapi.yaml b/docs/openapi/apis/cf/latest/openapi.yaml index dcd3c9cbcb5..208350e1cb1 100644 --- a/docs/openapi/apis/cf/latest/openapi.yaml +++ b/docs/openapi/apis/cf/latest/openapi.yaml @@ -1,7 +1,2080 @@ openapi: 3.1.0 info: title: Cloud Foundry V3 API - 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. " + description: |- + > **Note:** This OpenAPI specification is experimental and is not yet ready for production use. + + # Introduction + + ## Overview + + Welcome to the Cloud Foundry V3 API docs! Version 3 adds support for several + key features: + + * Running one-off tasks on Cloud Foundry + * Applications consisting of several processes via a Procfile + * Direct access to application packages and droplets + * Changing application source code without stopping the app via deployments + + ## Getting help + The CAPI team can most easily be reached on our [Slack channel](https://cloudfoundry.slack.com/archives/C07C04W4Q) 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](https://github.com/cloudfoundry/cloud_controller_ng). + + We recommend reaching out to Slack first as we will be most responsive there. + + ## More resources + + * The [Cloud Foundry V2 API](http://v2-apidocs.cloudfoundry.org/) is still available for interacting with Cloud Foundry. + * [Running Tasks](https://docs.cloudfoundry.org/devguide/using-tasks.html) + * [V3 API Documentation Source Code](https://github.com/cloudfoundry/cloud_controller_ng/tree/main/docs/v3) + + # Concepts + + ## API Resource + + A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object. + + A resource consists of several required resource fields and other attributes specific to the resource. + + See [Resources](#resources) and [Experimental Resources](#experimental-resources) for specific resources. + + ### Required fields + **Example Person Resource** + + ```json + { + "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2", + "created_at": "2016-03-18T23:26:46Z", + "updated_at": "2016-10-17T20:00:42Z", + + "name": "Bob", + + "links": { + "self": { + "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2" + } + } + } + ``` + + Name | Type | Description + ---- | ---- | ----------- + **guid** | _uuid_ | The unique identifier for the resource + **created_at** | _[timestamp](#timestamps)_ | The ISO8601 compatible date and time when resource was created + **updated_at** | _[timestamp](#timestamps)_ | The ISO8601 compatible date and time when resource was last updated + **links** | [_links object_](#links) | URLs to related resources and actions for the current resource + + ### Links + + Links provide URLs to [relationships](#relationships) and actions for a resource. Links are represented as a JSON object and always contain a `self` link. + + 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`. + + #### The link object + + **Example Link object** + + ```json + { + "href": "http://example.com/some/endpoint", + "method": "POST" + } + ``` + + Name | Type | Description + ---- | ---- | ----------- + **href** | _string_ | The absolute URL + **method** | _string_ | An optional field containing the HTTP method to be used when following the URL + + ## Authentication + The Cloud Foundry V3 API is secured using OAuth 2. Clients are expected to present a valid bearer token via HTTP header: `Authorization: bearer ` + + Tokens can be obtained from the Cloud Foundry UAA server. For more information, see the [UAA API Documentation](http://docs.cloudfoundry.org/api/uaa/index.html) + + > **Note:** Use the CF CLI to obtain a bearer token: `cf oauth-token` + + ## Authorization + + Access to resources is determined by combining scopes in the OAuth 2 token with user roles that are managed by the API. + + #### OAuth 2 scopes + + Scope | Description + ---------- | ------- + `cloud_controller.admin` | This scope provides read and write access to all resources + `cloud_controller.admin_read_only` | This scope provides read only access to all resources + `cloud_controller.global_auditor` | This scope provides read only access to all resources except secrets (such as environment variables) + `cloud_controller.read` | This scope provides read access to resources based on user roles + `cloud_controller.write` | This scope provides write access to resources based on user roles + `cloud_controller.update_build_state` | This scope allows its bearer to update the state of a build; currently only used when [updating builds](#update-a-build) + `cloud_controller_service_permissions.read` | This scope provides read only access for [service instance permissions](#get-permissions-for-a-service-instance) + + #### Cloud Foundry user roles + + Users that interact with the API should have one or more of these roles. Some of them (e.g. admin) + are controlled via scopes on the user's token. Others (e.g. space developer) are controlled via the + [roles resource](#roles). + + Role | Description + ---------------------------------------------------- | ------- + Admin | Allows a user to manage the platform; OAuth token must contain `cloud_controller.admin` scope + Admin Read-Only | Allows a user to read all resources on the platform; OAuth token must contain `cloud_controller.admin_read_only` scope + Global Auditor | Allows a user to read all resources on the platform, excluding sensitive data such as environment variables and service bindings. OAuth token must contain `cloud_controller.global_auditor` scope + Org User | Allows a user to be assigned other roles within an organization and its spaces + Org Manager | Provides organization management access + Org Auditor | Provides read-only access to an organization for auditing purposes + Org Billing Manager | Allows a user to create and manage billing account and payment information + Space Developer | Allows developers to create and manage apps and services in a space + Space Manager | Provides space management access + Space Auditor | Provides read-only access to a space for auditing purposes + Space Supporter | Troubleshoot and debug apps and service bindings in a space + + #### Component roles + + Components that interact with the Cloud Controller in the back-end can be given these roles to allow + limited access to API resources. These roles are controlled via scopes on the component's token. + + Role | Description + ---- | ----------- + Build State Updater | Allows a component to update the state of build resources; OAuth token must contain `cloud_controller.update_build_state` scope + + ## Embed + + The experimental `embed` parameter allows clients to fetch resources and include information of related pseudo-resources directly in the response. This is different from the [`include`](#include) parameter, which is used for fetching parent resources. + + **Important:** The `embed` feature is specifically designed for pseudo-resources that, by design, do not have their own list endpoint. These are resources that are tightly coupled to their parent resource and only make sense in the context of that parent. While they may have a GET endpoint to retrieve them individually for a specific parent, they cannot be listed independently across all parents. + + For example, `process_instances` is a pseudo-resource that provides a lightweight view of process instance states. It can be embedded into process resources to avoid making additional API calls, but you cannot list all process instances across all processes in the system. + + Developers may choose to use the `embed` feature to reduce the number of API calls. The embed query param can be used with a single resource or a list of resources. + + ### Resources with embed + + The following resources can take an `embed` parameter: + + Resource | Allowed values + -------- | -------------- + **processes** | `process_instances` + **processes/[:guid]** | `process_instances` + **apps/[:guid]/processes** | `process_instances` + **apps/[:guid]/processes/[:type]** | `process_instances` + + ## Errors + + **Example Error** + + ```json + { + "errors": [ + { + "code": 10008, + "title": "CF-UnprocessableEntity", + "detail": "something went wrong" + } + ] + } + ``` + + An error response will always return a list of error objects. Errors appear on the [job resource](#jobs) for asynchronous operations. + + ### The error object + + Clients should use the `code` and `title` fields for programmatically handling specific errors. + The message in the `detail` field is subject to change over time. + + Name | Type | Description + ---- | ---- | ----------- + **code** | _integer_ | A numeric code for this error + **title** | _string_ | Name of the error + **detail** | _string_ | Detailed description of the error + + ### Common errors + + These are some of the more common errors returned by many endpoints. + + Title | Code | HTTP Status | Description + ----- | ---- | ----------- | ----------- + `CF-BadQueryParameter` | 10005 | 400 | An invalid query parameter was given + `CF-InvalidAuthToken` | 1000 | 401 | An invalid auth token was given + `CF-NotAuthenticated` | 10002 | 401 | No auth token was given, but authentication is required for this endpoint + `CF-NotAuthorized` | 10003 | 403 | The authenticated user does not have permission to perform this operation + `CF-ResourceNotFound` | 10010 | 404 | The specified resource does not exist, or the authenticated user cannot read it + `CF-UnprocessableEntity` | 10008 | 422 | Catch-all error when an operation fails to complete; the `detail` field will contain more information + `CF-UaaRateLimited` | 20008 | 429 | Too many requests were made to the UAA instance. The request can be retried after the period stated in the `Retry-After` header + `UnknownError` | 10001 | 500 | An unexpected, uncaught error occurred; the CC logs will contain more information + + ## Fields + + The `fields` parameter allows clients to fetch resources and include information of parent objects + in the response. It works in a similar way to [include](#include), but the response only displays + the requested fields rather than the entire resource. + + For example, a response to `/v3/service_instances/:guid?fields[space.organization]=name` will contain detailed + information about the service instance, as well as the name of the organization it belongs to. + + Developers may choose to use the `fields` feature to reduce the number of API calls. The fields + query param can be used with a single resource or a list of resources. + + The fields query parameter may also grant visibility to parts of resources where the whole resource is not visible. + For instance, the name of an organization may be retrieved with fields, where the whole organization resource may + not be visible. + + ### Fields parameter + The fields parameter is structured as: `fields[resource]=keys&fields[parent.resource]=other,keys` + + - `resource` is the name of the resource being requested, qualified by the relationship to the current resource. + For example `/v3/service_instances?fields[space]=name` where `space` is a direct relationship of a service instance, + or `/v3/service_instances?fields[space.organization]=name` where `organization` is a relationship of `space`. + - `keys` is a comma-separated list of the fields in the object being requested. For example, + `/v3/service_instances?fields[space]=name,guid` will return just the `name` and `guid` of the space in the includes section. + + For information on `fields` support for each resource refer to its documentation. + + ### Resources with Fields + + Resource | Endpoint + -------- | -------------- + **Service Instances** | [v3/service_instances](#list-service-instances), [v3/service_instances/:guid](/#get-a-service-instance) + **Shared Spaces** | [/v3/service_instances/:guid/relationships/shared_spaces](#list-shared-spaces-relationship) + **Service Offerings** | [v3/service_offerings](#list-service-offerings), [v3/service_offerings/:guid](/#get-a-service-offering) + **Service Plans** | [v3/service_plans](#list-service-plans), [v3/service_plans/:guid](/#get-a-service-plan) + + ### Fields Sample requests + + **Example request to service instances resource to include parent orgs and spaces** + + ```shell + curl "https://api.example.org/v3/service_instances?fields[space]=name,guid,relationships.organization&fields[space.organization]=name,guid" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example response** + + ```json + { + "pagination": { + "total_results": 2, + "...": "..." + }, + "resources": [ + { + "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170", + "name": "service_instance_1", + "...": "..." + }, + { + "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837", + "name": "service_instance_2", + "...": "..." + } + ], + "included": { + "spaces": [ + { + "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b", + "name": "space1", + "relationships": { + "organization": { + "data": { + "guid": "b2075a71-28b6-411a-a896-56f75d892f58" + } + } + } + }, + { + "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9", + "name": "space2", + "relationships": { + "organization": { + "data": { + "guid": "b56fbd01-296b-442b-8faf-a559aebf985e" + } + } + } + } + ], + "organizations": [ + { + "guid": "b2075a71-28b6-411a-a896-56f75d892f58", + "name": "org1" + }, + { + "guid": "b56fbd01-296b-442b-8faf-a559aebf985e", + "name": "org2" + } + ] + } + } + ``` + + ## Filters + + Endpoints which return lists of resources also support filtering the returned resources using query parameters. Each + resource's list endpoint documents the allowed filters for that endpoint. For details about the syntax of query parameters + in general, see [query parameters](#query-parameters). + + #### Examples + + ##### **Single value request** + `GET /v3/apps?names=the_name` + + This will return all apps with name `the_name`. + + ##### **Multiple value request** + `GET /v3/apps?names=first_name,second_name` + + This will return all apps with name `the_name` OR `second_name`. + + In the case of audit events, multiple timestamps can be requested, which will return all audit + events that occurred at those timestamps. In the following request, all audit events that occurred + New Year's just before midnight and July 4th at noon will be returned: + + `GET /v3/audit_events?created_ats=2019-12-31T23:59:59Z,2020-07-04T12:00:00Z` + + ###### **Exception** + The `label_selector` query parameter will act as AND function, not an OR. + + `GET /v3/spaces?label_selector=production,east_coast` + + This will return all spaces whose metadata has labels with keys `production` AND `east_coast`. + + ##### **Combined filters** + `GET /v3/apps?names=the_name&stacks=cflinuxfs4` + + This will return all apps with name `the_name` AND stack `cflinuxfs4`. + + ##### **Empty filters** + + An empty filter (`/v3/resources?fields=`) can mean either empty string (`""`) or `NULL`, depending on the resource type. + + `GET /v3/buildpacks?stacks=` + + This will return all buildpacks with stack `NULL`. + + `GET /v3/routes?hosts=hostname1,,hostname2` + + This will return all routes with hostname `"hostname1"`, `""` OR `"hostname2"`. + + #### Relational Operators + + Some fields (e.g. `created_at` and `updated_at`) can be filtered using relational operators when listing resources. + + For example, a response to `GET /v3/audit_events?created_ats[lt]=2020-06-30T12:34:56Z` will contain + audit events with a `created_at` timestamp strictly earlier than `2020-06-30T12:34:56Z`. + + Multiple relational operators can be combined to further refine the listed resources. For example, a + response to `GET /v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z` + will return all audit events occurring on New Year's Day. + + Timestamps must be in [standard timestamp format](#timestamps). + + ##### Valid relational operators + + **Operator** | **Description** + -------------|----------------- + **lt** | Return resources strictly less than the given value for the filtered attribute + **lte** | Return resources less than or equal to the given value for the filtered attribute + **gt** | Return resources strictly greater than the given value for the filtered attribute + **gte** | Return resources greater than or equal to the given value for the filtered attribute + + #### Exclusion Operator + + Some fields support filtering on all values except a given set of values. + + For example, a response to `GET /v3/audit_events?target_guids[not]=guid-1,guid-2` + will contain audit events with a `target.guid` not equal to `guid-1` nor `guid-2`. + + **Operator** | **Description** + -------------|----------------- + **not** | Return resources not equal to the given value(s) for the filtered attribute + + ## Include + + The `include` parameter allows clients to fetch resources and include information of parent objects in the response. + For example, a response to `/v3/spaces/:guid?include=organization` will contain detailed information about the space and its parent organization. + + Developers may choose to use the `include` feature to reduce the number of API calls. The include + query param can be used with a single resource or a list of resources. + + ### Resources with includes + + The following resources can take an `include` parameter: + + Resource | Allowed values + -------- | -------------- + **apps** | `space.organization`, `space` + **apps/[:guid]** | `space.organization`, `space` + **roles** | `user`, `space`, `organization` + **roles/[:guid]** | `user`, `space`, `organization` + **routes** | `domain`, `space.organization`, `space` + **routes/[:guid]** | `domain`, `space.organization`, `space` + **service_plans** | `space.organization`, `service_offering` + **service_plans/[:guid]** | `space.organization`, `service_offering` + **service_credential_bindings** | `app`, `service_instance` + **service_credential_bindings/[:guid]** | `app`, `service_instance` + **service_route_bindings** | `route`, `service_instance` + **service_route_bindings/[:guid]** | `route`, `service_instance` + **spaces** | `organization` + **spaces/[:guid]** | `organization` + + ### Sample requests + + **Example request to apps resource to include parent orgs and spaces** + + ```shell + curl "https://api.example.org/v3/apps?include=space.organization" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example response** + + ```json + { + "pagination": { + "total_results": 2, + "...": "..." + }, + "resources": [ + { + "guid": "42ad8d5a-8124-4fc7-baf2-3f39bfe1c170", + "name": "app1", + "...": "..." + }, + { + "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837", + "name": "app2", + "...": "..." + } + ], + "included": { + "spaces": [ + { + "guid": "134f95ad-b5eb-4b55-9ce0-b906c513d54b", + "name": "space1", + "...": "..." + }, + { + "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9", + "name": "space2", + "...": "..." + } + ], + "organizations": [ + { + "guid": "b2075a71-28b6-411a-a896-56f75d892f58", + "name": "org1", + "...": "..." + }, + { + "guid": "b56fbd01-296b-442b-8faf-a559aebf985e", + "name": "org2", + "...": "..." + } + ] + } + } + ``` + + **Example request for a single app instance to include its parent space** + + ```shell + curl "https://api.example.org/v3/apps/[guid]?include=space" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example response** + + ```json + { + "guid": "b90f287b-fcdd-4cbb-9523-1a8dbd2a9837", + "name": "staticfile", + "...": "...", + "included": { + "spaces": [ + { + "guid": "00b76d5c-5176-4cbc-be5d-0bd76363dca9", + "name": "space1a", + "...": "..." + } + ] + } + } + ``` + + ## Lifecycles + + Lifecycles inform the platform of how to build droplets and run apps. For example, a `docker` lifecycle will + pull a Docker image from a registry to run an app. + + #### The lifecycle object + + Name | Type | Description + ---- | ---- | ----------- + **type** | _string_ | Type of the lifecycle; valid values are `buildpack`, `cnb`, `docker` + **data** | _object_ | Data that is used during staging and running for a lifecycle + + ### Buildpack lifecycle + + **Example Buildpack Lifecycle** + + ```json + { + "type": "buildpack", + "data": { + "buildpacks": ["java_buildpack"], + "stack": "cflinuxfs4" + } + } + ``` + + This is the default lifecycle for Cloud Foundry for VMs. When staging an app with this lifecycle, the app source code will be + compiled using a buildpack, resulting in a droplet. When running an app with this lifecycle, a container running a rootfs + will be created and the droplet will be expanded inside that container to be executed. + + If buildpacks are not specified, then Cloud Foundry will automatically detect a + compatible buildpack, based on the files in an app's package. If a stack is not + specified, then the app will default to the operator-configured default stack. + + #### Buildpack lifecycle object + + Name | Type | Description + ---- | ---- | ----------- + **type** | _string_ | `buildpack` + **data.buildpacks** | _list of strings_ | A list of the names of buildpacks, URLs from which they may be downloaded, or `null` to auto-detect a suitable buildpack during staging + **data.stack** | _string_ | The root filesystem to use with the buildpack, for example `cflinuxfs4` + + For records whose historical lifecycle data is no longer available, + **data.buildpacks** may be an empty list and **data.stack** may be `null`. + + ### Cloud Native Buildpacks Lifecycle *(experimental)* + + **Example Cloud Native Buildpacks lifecycle** + + ```json + { + "type": "cnb", + "data": { + "buildpacks": [ + "docker://example.org/java-buildpack:latest" + "docker://second-example.org/logging-buildpack:latest" + ], + "stack": "cflinuxfs4", + "credentials": { + "example.org": { + "username": "user", + "password": "****" + }, + "second-example.org": { + "token": "****" + }, + } + } + } + ``` + + This lifecycle allows Cloud Foundry to stage an application using the [Cloud Native Buildpacks](https://buildpacks.io/). + + **Note**: the **data.buildpacks** field is required (at least 1 buildpack must be set). + + #### Cloud Native Buildpacks lifecycle object + + Name | Type | Description + ---- | ---- | ----------- + **type** | _string_ | `cnb` + **data.buildpacks** | _list of strings_ | A list of URLs with either `docker://` or `http(s)://` scheme, pointing to the Cloud Native Buildpack OCI image.
When the scheme is `http(s)://`, an OCI tarball is expected to be present at the specified location. + **data.credentials** | _object_ | Credentials used to download the configured buildpacks. This can either contain username/password or a token. + **data.stack** | _string_ | The root filesystem to use with the buildpack, for example `cflinuxfs4` + + For records whose historical lifecycle data is no longer available, + **data.buildpacks** may be an empty list and **data.stack** may be `null`. + + ### Docker lifecycle + + **Example Docker Lifecycle** + + ```json + { + "type": "docker", + "data": {} + } + ``` + + This allows Cloud Foundry to run pre-built Docker images. When staging an app with this lifecycle, the Docker registry is queried for + metadata about the image, such as ports and start command. When running an app with this lifecycle, a container is created + and the Docker image is executed inside of it. + + #### Docker lifecycle object + + Name | Type | Description + ---- | ---- | ----------- + **type** | _string_ | `docker` + **data** | _object_ | Data is not used by the Docker lifecycle; valid value is `{}` + + ## Metadata + + Metadata allows you to tag [API resources](#api-resource) with information that does not directly affect its functionality. + + ### Annotations + + **Example Resource with Annotations** + + ```json + { + "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2", + "created_at": "2016-03-18T23:26:46Z", + "updated_at": "2016-10-17T20:00:42Z", + "name": "api-server", + "metadata": { + "labels": {}, + "annotations": { + "contacts": "Bill tel(1111111) email(bill@fixme), Bob tel(222222) pager(3333333#555) email(bob@fixme)" + } + }, + "links": { + "self": { + "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2" + } + } + } + ``` + + Annotations are user-specified key-value pairs that are attached to [API resources](#api-resource). They do not affect the operation of Cloud Foundry. Annotations cannot be used in [filters](#filters). + + When a service instance is being created, the service broker is sent the annotations of the service instance, and the space and organization in which the service instance resides. + When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance resides. + When a service binding is being created, the service broker is sent annotations of any associated app, and the space and organization in which the binding resides. + Only annotations with a prefix (e.g. `company.com/contacts`) are sent to service brokers. + + Examples may include (but are not limited to): + + - `"contact-info": "bob@example.com jane@example.com"` + - `"library-versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38"` + - `"git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512"` + + #### Annotation keys + + Annotation keys are made up of an (optional) prefix and name. If a prefix is present, it is separated from the name by a `/`. + Prefixes are DNS names intended to enable namespacing of annotation keys. + + An annotation key `prefix` must adhere to the following restrictions: + + * Length: 0-253 characters + * Allowed characters: a-z, A-Z, 0-9, `-`, and `.`; emojis cannot be used in keys + * DNS subdomain format (series of subdomain annotations separated by `.`) + + An annotation key `name` must adhere to the following restrictions: + + * Length: 1-63 characters + * Allowed characters: a-z, A-Z, 0-9, `-`, `_`, and `.`; emojis cannot be used in keys + * Must begin and end with an alphanumeric character + + #### Annotation values + + Annotation values must adhere to the following restrictions: + + * Length: 0-5000 unicode characters + + ### Labels and selectors + + **Example Resource with Labels** + + ```json + { + "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2", + "created_at": "2016-03-18T23:26:46Z", + "updated_at": "2016-10-17T20:00:42Z", + "name": "api-server", + "metadata": { + "labels": { + "environment": "production", + "internet-facing": "false" + }, + "annotations": {} + }, + "links": { + "self": { + "href": "https://api.example.org/v3/apps/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2" + } + } + } + ``` + + Labels are user-specified key/value pairs that are attached to [API Resources](#api-resource). + They are queryable, identifying attributes of a resource, but they do not affect the operation of CloudFoundry. + + For example, an app may be assigned a label with key `sensitive` and possible values `true` or `false`. + + Users could then find all sensitive apps with a selector for `sensitive=true`, resulting in a response containing + only apps having the label key `sensitive` with a label value of `true`. + + #### Labels + + Labels allow users to apply identifying attributes to resources that are meaningful to the user, but not the CloudFoundry system. + + Examples may include (but are not limited to): + + - `"production" : "true"` or `"production" : "false"` + - `"env" : "dev"` or `"env" : "test"` or `"env" : "prod"` + - `"chargeback-code" : "abc123"` + + ##### Label keys + + Label keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a `/`. + Prefixes are dns names intended to enable namespacing of label keys. + + A label key `prefix` must adhere to the following restrictions: + + * Length: 0-253 characters + * Allowed characters: alphanumeric ( \[a-z0-9A-Z\] ), `-`, and `.` + * DNS subdomain format (series of subdomain labels separated by `.`) + + A label key `name` must adhere to the following restrictions: + + * Length: 1-63 characters + * Allowed characters: alphanumeric ( \[a-z0-9A-Z\] ), `-`, `_`, and `.` + * Must begin and end with an alphanumeric character + + ##### Label values + + Label values must adhere to the following restrictions: + + * Length: 0-63 characters + * Allowed characters: alphanumeric ( \[a-z0-9A-Z\] ), `-`, `_`, and `.` + * Must begin and end with an alphanumeric character + * Empty values are allowed + + #### Selectors + + **Example label selector** + + ```bash + cf curl /v3/apps?label_selector=env=dev,%21chargeback-code,tier%20in%20%28backend,worker%29 + ``` + + Selectors allow users to filter and group API resources by the labels applied to them. A selector consists of one or + more `requirements` in a comma-delimited list. The maximum number of `requirements` in a single selector is 50. + + _eg:_ `env=dev,!chargeback-code,tier in (backend,worker)` + + Selectors can be used to filter and group resources using the query parameter `label_selector` on list endpoints. + + > **Note:** When included in a url, the selector must be appropriately escaped. + + A requirement consists of a _key_, an `operator`, and optional _value(s)_. + + Requirement | Format | Description + ----------- | ------ | ----------- + existence | _key_ | Returns all resources that have been assigned a label with the given _key_ (with any _value_) + non-existence | `!`_key_ | Returns all resources that have not been assigned a label with the given _key_ (with any _value_) + equality | _key_`=`_value_ or _key_`==`_value_ | Returns all resources that have been assigned a label with the given _key_ and _value_ + inequality | _key_`!=`_value_ | Returns all resources that either have not been assigned a label with the given _key_ or have a label with the given _key_ but a different _value_ + set inclusion | _key_ `in` (_value1_,_value2_...) | Returns all resources that have been assigned a label with the given _key_ with one of the specified _value(s)_ + set exclusion | _key_ `notin` (_value1_,_value2_...) | Returns all resources that either have not been assigned a label with the given _key_ or have a label with the given _key_ but none of the specified _value(s)_ + + See [the metadata documentation](https://docs.cloudfoundry.org/adminguide/metadata.html#query) for more information. + + ### Updating labels and annotations + + **Example Initial Metadata** + + ```json + { + "metadata": { + "labels": { + "environment": "staging", + "ready-to-deploy": "true" + }, + "annotations": { + "spring-version": "5.1", + "app-version": "0.1-alpha" + } + } + } + ``` + + **Example Patch Request Body** + + ```json + { + "metadata": { + "labels": { + "environment": "production", + "ready-to-deploy": null + }, + "annotations": { + "app-version": "0.1", + "deployed-month": "november" + } + } + } + ``` + + **Example Final Metadata** + + ```json + { + "metadata": { + "labels": { + "environment": "production" + }, + "annotations": { + "spring-version": "5.1", + "app-version": "0.1", + "deployed-month": "november" + } + } + } + ``` + + Labels and annotations can be updated by using the PATCH endpoint for their resource. + For example, to update labels or annotations on an app, use the [update an app](#update-an-app) endpoint. + When patching metadata, CAPI endpoints do a deep merge, only updating labels or annotations that are specified in the request. + + Labels and annotations follow the same rules for patching and must be wrapped in the metadata object inside the request body + + * To create, include the new key with a value + * To change, include the existing key with a new value + * To delete, include the existing key with a `null` value + * To remain unchanged, do not include the existing key. + + ## Pagination + + **Example Paginated Response** + + ```json + { + "pagination": { + "total_results": 3, + "total_pages": 3, + "first": { + "href": "https://api.example.org/v3/people?page=1&per_page=1" + }, + "last": { + "href": "https://api.example.org/v3/people?page=3&per_page=1" + }, + "next": { + "href": "https://api.example.org/v3/people?page=2&per_page=1" + }, + "previous": null + }, + "resources": [ + { + "guid": "fd35633f-5c5c-4e4e-a5a9-0722c970a9d2", + "created_at": "2016-03-18T23:26:46Z", + "updated_at": "2016-10-17T20:00:42Z", + "name": "Bob", + "links": { + "self": { + "href": "https://api.example.org/v3/people/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2" + } + } + } + ] + } + ``` + + Any request that can return multiple resources will be paginated and contain a `pagination` object and list of `resources`. + Requests for multiple resources can use `page`, `per_page`, and `order_by` in addition to filters specific to the endpoint. + + #### The pagination object + + Name | Type | Description + ---- | ---- | ----------- + **total_results** | _integer_ | Total number of resources for all pages + **total_pages** | _integer_ | Total number of pages + **first** | [_link object_](#the-link-object) | Link to the first page + **last** | [_link object_](#the-link-object) | Link to the last page + **next** | [_link object_](#the-link-object) | Link to the next page + **previous** | [_link object_](#the-link-object) | Link to the previous page + + ## Procfiles + + **Example Ruby Procfile** + + ```yaml + web: bundle exec rackup config.ru -p $PORT + rake: bundle exec rake + worker: bundle exec rake workers:start + ``` + + A Procfile enables you to declare required runtime processes, called process types, for your app. + Procfiles must be named `Procfile` exactly and placed in the root directory of your application. + + In a Procfile, you declare one process type per line and use the syntax `PROCESS_TYPE: COMMAND`. + + - `PROCESS_TYPE` defines the type of the process. + - `COMMAND` is the command line to launch the process. + + #### Procfile use cases + + Many buildpacks provide their own process types and commands by default; however, there are special + cases where specifying a custom `COMMAND` is necessary. Commands can be overwritten by providing a + Procfile with the same process type. + + For example, a buildpack may provide a `worker` process type that runs the `rake default:start` + command. If a Procfile is provided that also contains a `worker` process type, but a different + command such as `rake custom:start`, the `rake custom:start` command will be used. + + Some buildpacks, such as Python, that work on a variety of frameworks, do not attempt to provide a + default start command. For these cases, a Procfile should be used to specify any necessary commands + for the app. + + #### Web process + + `web` is a [special process type](#web-process-type) that is required for all applications. + The `web` `PROCESS_TYPE` must be specified by either the buildpack or the Procfile. + + #### Specifying processes in manifest files + + Custom process types can also be configured via a manifest file. Read more about + [manifests](#manifests). It is not recommended to specify processes in both a manifest and a + Procfile for the same app. + + ## Query Parameters + + Clients can assume that query parameters on the API will always follow these rules: + + - Parameter names (before the `=`, and ignoring any modifiers like `[gt]`) will only contain characters `a-z` (lowercase) and `-`. + - When a parameter accepts multiple values, these will be represented as a comma-delimited list of strings (see [filters](#filters)). + + Because commas are used to separate list entries, **parameter values that contain commas must be percent-encoded**. For example, to retrieve apps named either `a,b` or `c,d`, the query parameter would look like `names=a%2Cb,c%2Cd`. Note that the commas within the app names are encoded (as `%2C`), but the comma separating the two app names is not. The resulting query parameter must be encoded a second time before sending it to the API, e.g. `cf curl /v3/apps?names=a%252Cb,c%252Cd`. + + ## Relationships + + Relationships represent associations between resources. When relationships are mutable, they can be + used to create, read, update, and delete these associations. An app's relationship to its current + droplet is mutable, but an app's relationship to its space is not. + + Relationships do not affect the fundamental properties of a resource, but may affect their behavior + and permissions logic. Relationships are tied to the lifecycles of the associated resources and + will be removed if either of the associated resources are deleted. For example, if a user is removed + from an organization, both the user and the organization persist, but the relationship between them + does not. + + Not all resources implement every relationship operation demonstrated in the examples below. See the + docs for each resource to see how it interacts with its relationships. + + Endpoints that return relationship data list this information under the `relationships` key. + + #### The relationship object + + The relationship object is a key-value pair that uniquely identifies a resource. In practice this is + almost always the `guid` of a resource. + + Name | Type | Description + ---- | ---- | ----------- + **guid** | _string_ | The unique identifier for the related resource + + ### To-one relationships + + **Example to-one relationship** + + ```json + { + "data": { + "guid": "[related-resource-guid]" + } + } + ``` + + Some relationships relate a resource to exactly one other resource. For example an app can belong to + only one space. + + #### To-one relationship object + + Name | Type | Description + ---- | ---- | ----------- + **data** | _[relationship object](#the-relationship-object)_ | A single relationship + + **Setting the to-one relationship while creating an object** + + ```shell + curl "https://api.example.org/v3/books" \ + -X POST \ + -H "Authorization: bearer [token]" \ + -H "Content-type: application/json" \ + -d '{ + "color": "yellow", + "relationships": { + "publisher": { + "data": { + "guid": "publisher-guid" + } + } + } + }' + ``` + + **Modifying the to-one relationship** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \ + -X PATCH \ + -H "Authorization: bearer [token]" \ + -H "Content-type: application/json" \ + -d '{ + "data": { + "guid": "publisher-guid" + } + }' + ``` + + **Removing the to-one relationship** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \ + -X PATCH \ + -H "Authorization: bearer [token]" \ + -H "Content-type: application/json" \ + -d '{ "data": null }' + ``` + + **Viewing the to-one relationship** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/publisher" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + ### To-many relationships + + **Example to-many relationship** + + ```json + { + "data": [ + { "guid": "[related-resource-guid-1]" }, + { "guid": "[related-resource-guid-2]" } + ] + } + ``` + + Some relationships relate a resource to several other resources. For example, an isolation segment can be entitled to multiple organizations. + + #### To-many relationship object + + Name | Type | Description + ---- | ---- | ----------- + **data** | _array of [relationship objects](#the-relationship-object)_ | An array of multiple relationships + + **Adding related to-many resources** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/authors" \ + -X POST \ + -H "Authorization: bearer [token]" \ + -H "Content-type: application/json" \ + -d '{ + "data": [ + { "guid":"author-guid-1" }, + { "guid":"author-guid-2" } + ] + }' + ``` + + **Replacing all to-many relationships** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/authors" \ + -X PATCH \ + -H "Authorization: bearer [token]" \ + -H "Content-type: application/json" \ + -d '{ + "data": [ + { "guid":"author-guid-3" }, + { "guid":"author-guid-4" } + ] + }' + ``` + + **Removing all to-many relationships** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/authors" \ + -X PATCH \ + -H "Authorization: bearer [token]" \ + -H "Content-type: application/json" \ + -d '{ "data": [] }' + ``` + + **Removing specific to-many relationships** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/authors/[author-guid]" \ + -X DELETE \ + -H "Authorization: bearer [token]" + ``` + + **Viewing the to-many relationships** + + ```shell + curl "https://api.example.org/v3/books/[guid]/relationships/authors" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + ## Status Codes + + Cloud Foundry V3 API uses a subset of HTTP response codes to indicate the success or failure of an API request. + In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that can potentially be fixed by correcting the request, and codes in the 5xx range indicate an error on the server side. + + HTTP Status Code | Description + ---------- | ------- + 200 OK | The request completed successfully + 201 Created | The request completed successfully and created a new resource + 202 Accepted | The request will be completed asynchronously; see [asynchronous operations](#asynchronous-operations) + 204 No Content | The request completed successfully and did not return a body + 400 Bad Request | The request has malformed or invalid data + 401 Unauthenticated | The request requires an authenticated user + 403 Forbidden | The request cannot be performed by the user + 404 Not Found | The requested resource does not exist + 422 Unprocessable Entity | The request cannot be performed + 500 Internal Server Error | An unexpected error occurred + 502 Bad Gateway | An external upstream service caused the request to fail + 503 Service Unavailable | An internal upstream service caused the request to fail + + ## Timestamps + + Timestamps generally appear in `created_at` and `updated_at` fields on resources. Precision beyond + seconds is not supported, even if the underlying database supports it (e.g. Postgres). As a result, + filtering on sub-second timestamps is not allowed. + + All v3 timestamps have the following format `YYYY-MM-DDThh:mm:ssZ`. + + Example timestamp (June 30, 2020 at 11:49:04 PM UTC): `2020-06-30T23:49:04Z` + + ## Updating Actual State + + The Cloud Controller is primarily responsible for the desired state of apps and processes. Most endpoints will + only update the desired states of your apps and processes within Cloud Controller in order + to provide users with the opportunity to incur zero downtime when updating apps. Restarting + the app will be required for the desired state changes to become the actual state. + + The [stats endpoint](#get-stats-for-a-process) can be used at any time to determine the actual + (running) state of a process, and by proxy, an app. + + #### Endpoints that will affect runtime + + The following endpoints will immediately impact the runtime of the app, and the desired changes will take effect without needing to [restart the app](#restart-an-app). + + |Endpoint| + |------| + |[`PATCH /v3/spaces/:guid/features/ssh`](#get-ssh-enabled-for-an-app)| + |[`DELETE /v3/routes/:guid/destinations/:destination_guid`](#remove-destination-for-a-route)| + + The following endpoints will immediately impact runtime and take effect when **only** the `instances` field is updated. If any other fields are updated, the app will need to be restarted in order for any desired changes to take effect, including instance count changes. + + |Endpoint| + |------| + |[`POST /v3/processes/:guid/actions/scale`](#scale-a-process)| + |[`POST /v3/apps/:guid/processes/:type/actions/scale`](#scale-a-process)| + + The following endpoints will immediately impact runtime and the desired changes will take effect if the specified fields are **not** included in the request. + + If the field is specified, the app will need to be restarted in order for any desired changes to take effect. + + |Endpoint| Changes requiring a restart| + |------|------| + |[`POST /v3/routes/:guid/destinations`](#insert-destinations-for-a-route)| Adding a destination with a port| + |[`PATCH /v3/routes/:guid/destinations`](#replace-all-destinations-for-a-route)| Replacing the port field

*Note: If the port is specified, this endpoint will unmap any route not listed in the body but will not map any of the new routes in the request body. For this reason we caution against using the endpoint in most circumstances. A combination of [adding ports](#insert-destinations-for-a-route) and [removing ports](#remove-destination-for-a-route) will better fit most use cases.*| + + All other changes will not take effect on running apps until they are restarted. + + ## Warnings + + **Example Warnings** + + ```json + { + "warnings": [ + { + "detail": "something went wrong" + } + ] + } + ``` + + Warnings appear on the [job resource](#jobs). + + #### The warning object + + Name | Type | Description + ---- | ---- | ----------- + **detail** | _string_ | Description of the warning + + # Upgrade Guide + + This document is intended to help client authors upgrade from Cloud Foundry's V2 API to the V3 API. + + When moving to the V3 API, it is important to understand that the V3 API is backed by the same database as the V2 API. Though resources may be presented differently and have different interaction patterns, the internal state of CF is the same across both APIs. If you create an organization using the V3 API, + it will be visible to the V2 API, and vice-versa. + + If you have questions, need help, or want to chat about the upgrade process, please reach out to us in [Cloud Foundry Slack](https://cloudfoundry.slack.com/archives/C07C04W4Q). + + ## Conceptual Changes + + ### App Sub-Resources + + The V2 API rolls up several resources into its representation of an "app": + + 1. **Packages:** Source assets for the application + 2. **Droplets:** Staged, executable assets for the application + 3. **Builds:** Configuration for how to stage the package into a droplet + 4. **Processes:** Configuration for how to run the droplet + + The V3 API exposes these resources on the API to provide more visibility and enable more complicated workflows. For example: + + 1. Staging a previous package into a new droplet + 2. Rolling back to a previous droplet + 3. Staging a droplet to run a task, without running any processes + 4. Running multiple different processes from a single droplet (for example: a web process and a worker process) + + Here are some examples of implications for clients: + + 1. The app resource contains much less information about the application as a whole + 2. An application can have multiple processes, each with their own start command. The processes can be scaled independently, and stats be retrieved independently. + 3. An application might not be running with its most recent package or droplet + + ### Starting Apps + + In the V2 API, starting an app (`PUT /v2/apps/:GUID` with `state`: `STARTED`) will automatically stage new packages into droplets. In V3, [starting an app](#start-an-app) will only run the app's current droplet. This change gives clients more control over what package to stage and when to stage it. + + To reproduce the V2 start behavior in V3: + + ![Start Diagram](start_diagram.png) + + 1. [List packages](#list-packages) and filter on package state with value `READY` and order by recency. + 1. If a package has been turned into a droplet [(see this endpoint)](#list-droplets-for-a-package) this means it has been staged already. In V2 workflows, this would mean this package is what the current droplet is running. + 1. Stage the package by [creating a build](#create-a-build). This turns your package into a droplet. + 1. Update the app’s [current droplet](#set-current-droplet) to the selected droplet. This droplet will be run when the app starts. + 1. Change the app’s state to [started](#start-an-app) + + This gives V3 users more flexibility when managing applications. The following + diagram shows many different flows for starting an app. + + ![Start Flow](start_flows.png) + + Apps can upload multiple packages, stage multiple droplets, roll back to older droplets, and other complicated workflows. + + ### Asynchronous Operations + + Unlike V2, clients cannot opt-in for asynchronous responses from endpoints. + Instead, endpoints that require asynchronous processing will return `202 Accepted` with a Location header pointing to the job resource to poll. + Endpoints that do not require asynchronous processing will respond synchronously. + + For clients that want to report the outcome of an asynchronous operation, poll the job in the Location header until its `state` is no longer `PROCESSING`. + If the job's `state` is `FAILED`, the `errors` field will contain any errors that occurred during the operation. + + An example of an asynchronous endpoint is the [delete app endpoint](#delete-an-app). + + Service related endpoints such as [service instance](#service-instances), [service credential binding](#service-credential-binding) and [service route binding](#service-route-binding) may create jobs + that transition to state `POLLING` after `PROCESSING`. This state reflects the polling of the last operation from the service broker. + For clients that want to report the outcome of this asynchronous operation, poll the job in the Location header until its `state` is no longer `POLLING`. + + Read more about [the job resource](#jobs). + + ### Errors + + **Example Request** + + ```shell + curl "https://api.example.org/v2/apps/not-found" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example Response** + + ```http + HTTP/1.1 404 Not Found + Content-Type: application/json + + { + "description": "The app could not be found: not-found", + "error_code": "CF-AppNotFound", + "code": 100004 + } + ``` + + **Example Request** + + ```shell + curl "https://api.example.org/v3/apps/not-found" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example Response** + + ```http + HTTP/1.1 404 Not Found + Content-Type: application/json + + { + "errors": [ + { + "detail": "App not found", + "title": "CF-ResourceNotFound", + "code": 10010 + } + ] + } + ``` + + The V3 API returns an array of errors instead of a single error like in V2. + + Clients may wish to display all returned errors. + + ### Filtering + + **Filters are specified as individual query parameters in V3** + + ```shell + curl "https://api.example.org/v2/apps?q=name+IN+dora,broker;stack:cflinuxfs4" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + ```shell + curl "https://api.example.org/v3/apps?names=dora,broker&stacks=cflinuxfs4" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + Filtering resources no longer uses V2's query syntax. See the example to the right. + + A few common filters have been also renamed in V3: + + |V2 filter|V3 filter| + |---|---| + |`results-per-page`|`per_page`| + |`page`|`page`| + |`order-by`|`order_by`| + |`order-direction`|N/A1| + + 1 In V3, order is ascending by default. Prefix the `order_by` value with `-` to make it descending. For example, `?order_by=-name` would order a list of resources by `name` in descending order. + + Filtering inequalities has changed in V3: V3 dispenses with the `q=` preamble, + uses `created_ats` instead of `timestamp` and uses bracket operators (`[lt]`, + `[gt]`, `[lte]`, `[gte]`). For example, to request all audit events occurring on + New Year's Day, one would use the following query: `GET + /v3/audit_events?created_ats[lt]=2020-01-02T00:00:00Z&created_ats[gt]=2019-12-31T23:59:59Z`. + + The corresponding V2 query would be `GET + /v2/events?q=timestamp<2020-01-02T00:00:00Z&q=timestamp>2019-12-31T23:59:59Z`. + + Filtering on equality has also changed: V3 dispenses with the `q=` preamble and + uses the pluralized field (e.g. `names`) on the left side of the equals sign. + For filtering on inclusion in a set, V3 allows passing multiple values separated + by commas. + + For example, to request the organizations by + their name ("finance" and "marketing"), one would use the following query: + `/v3/organizations?names=finance,marketing` + + The corresponding V2 query would be `GET + /v2/organizations?q=name%20IN%20finance,marketing` + + Read more about [filtering in V3](#filters). + + ### Including Associated Resources + + The `inline-relations-depth` parameter is no longer supported on V3. Instead, some resources support the `include` parameter to selectively include associated resources in the response body. + + For example, to include an app's space in the response: + ``` + cf curl /v3/apps/:guid?include=space + ``` + + In addition, some resources provide the possibility of including specified fields of a related resource. + + For example, to include the service broker `name` and `guid` in the service offering's response: + ``` + cf curl /v3/service_offerings/:guid?fields[service_broker]=name,guid + ``` + + Read more about [the `include` parameter](#include) and [the `fields` parameter](#fields). + + ### Resource Summaries + + V2 provided several endpoints that returned rolled-up summaries (e.g. + `/v2/spaces/:guid/summary` for a space summary, or + `/v2/organizations/:guid/summary` for an organization summary). Although + convenient, these endpoints have been largely removed from V3, for they were + computationally expensive and often returned much more information than + needed. + + In V3, to enable better API performance, these usage patterns are + deliberately disallowed. Instead, clients are encouraged to think more carefully + about which information they need and to fetch that information with + multiple API calls and/or by making use of the [`include` + parameter](#including-associated-resources) or [the `fields` parameter](#fields) on certain endpoints. + + In V2, summary endpoints provided a way to fetch all resources associated with a + parent resource. In V3, fetch the summary though the associated resource and + filter by the parent resource. See below for examples of summaries in V3. + + #### Replacing the space summary endpoint + + - To fetch all apps in a space, use `GET /v3/apps?space_guids=`. + Passing `include=space` will include the space resource in the response body. + - To fetch all service offerings in a space use `GET + /v3/service_offerings?space_guids=`. Use the + `fields` parameter to include related information in the response + body. + - To fetch all service instances in a space use `GET + /v3/service_instances?space_guids=`. Use the + `fields` parameter to include related information in the response + body. + + ##### Replacing the space summary response for service instances + + Similar fields to what `/v2/spaces/:guid/summary` was offering for services are available from v3 endpoints. + + The table below describes the query parameters needed to retrieve some of those fields using `/v3/service_instances` endpoint. + Same query parameters are available on the request for a single resource. + + |**V2 summary fields**|**V3 query**|**V3 response fields**| + |---|---|---| + | services[].service_plan.guid | fields[service_plan]=guid | resources[].included.service_plans[].guid | + | services[].service_plan.name | fields[service_plan]=name | resources[].included.service_plans[].name | + | services[].service_plan.service.guid | fields[service_plan.service_offering]=guid | resources[].included.service_offerings[].guid | + | services[].service_plan.service.label | fields[service_plan.service_offering]=name | resources[].included.service_offerings[].name | + | services[].service_broker_name | fields[service_plan.service_offering.service_broker]=name | resources[].included.service_brokers[].name | + | shared_from.space_guid | fields[space]=guid | resources[].included.spaces[].guid | + | shared_from.space_name | fields[space]=name | resources[].included.spaces[].name | + | shared_from.organization_name | fields[space.organization]=name | resources[].included.organizations[].name | + + The table below describes the query parameters needed to retrieve the sharing information using `/v3/service_instances/:guid/relationships/shared_spaces` endpoint. + + |**V2 summary fields**|**V3 query**|**V3 response fields**| + |---|---|---| + | shared_to.space_guid | fields[space]=guid | included.spaces[].guid | + | shared_to.space_name | fields[space]=name | included.spaces[].name | + | shared_to.organization_name | fields[space.organization]=name | included.organizations[].name | + + The existing `bound_app_count` field can be found by using the [usage summary endpoint](#get-usage-summary-in-shared-spaces) + + Read more about [the `fields` parameter](#fields). + + #### Replacing the user summary endpoint + + - The user summary was useful for finding organizations and spaces where a user + had roles. In V3, with the introduction of the role resource, you can use `GET + /v3/roles?user_guids=` to list a user's roles. Passing + `include=space,organization` will include the relevant spaces and organizations + in the response body. + + #### Usage summary endpoints + + There are still a couple of endpoints in V3 that provide a basic summary of + instance and memory usage. See the [org summary](#get-usage-summary), [space summary](#get-space-usage-summary) and + [platform summary](#get-platform-usage-summary) endpoints. + + ### Ports + + In V2, users exposed ports on an app by modifying the app's `ports` field. + + In V3, users expose ports on a process by creating destinations that map a route to a given app and process. For an app listening on multiple ports, users must create one destination per port. + + Read more about [routes, destinations, and ports](#routes). + + ## New Concepts + + ### Actions + + Actions are API requests that are expected to immediately initiate change within the Cloud Foundry runtime. This is differentiated from requests which update a record but require additional updates, such as restarting an app, to cause changes to a resource to take effect. + + Example: + ``` + POST /v3/apps/:guid/actions/start + ``` + + ### Links + + **Example Request** + + ```shell + curl "https://api.example.org/v3/apps/:guid" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example Response** + + ```json + { + "...": "...", + "links": { + "self": { + "href": "http://api.example.com/v3/apps/:guid" + }, + "space": { + "href": "http://api.example.com/v3/spaces/:space_guid" + } + } + } + ``` + + Links provide URLs to associated resources, relationships, and actions for a resource. + The example links to both the app itself and the space in which it resides. + + ### Metadata + + **Example Request** + + ```shell + curl "https://api.example.org/v3/:resource/:guid" \ + -X GET \ + -H "Authorization: bearer [token]" + ``` + + **Example Response** + + ```json + { + "...": "...", + "metadata": { + "labels": { + "environment": "production", + "internet-facing": "false" + }, + "annotations": { + "contacts": "Bill tel(1111111) email(bill@fixme)" + } + } + } + ``` + + Metadata allows you to tag and query certain API resources with information; metadata does not affect the resource's functionality. + + For more details and usage examples, see [metadata](#metadata) or [official CF docs](https://docs.cloudfoundry.org/adminguide/metadata.html). + + Note that metadata consists of two keys, `labels` and `annotations`, each of which consists of key-value pairs. API V3 allows filtering by labels (see [label_selector](#labels-and-selectors)) but not by annotations. + + ### Relationships + + **Example Request** + + ```shell + curl "https://api.example.org/v3/apps" \ + -X POST \ + -H "Authorization: bearer [token]" + -d '{ + "name": "testapp", + "relationships": { + "space": { "data": { "guid": "1234" }} + } + }' + ``` + + Relationships represent associations between resources: For example, every space belongs in an organization, and every app belongs in a space. The V3 API can create, read, update, and delete these associations. + + In the example request we create an app with a relationship to a specific space. + + One can retrieve or update a resource's relationships. For example, to retrieve an app's relationship to its space with the `/v3/apps/:app_guid/relationships/space` endpoint. + + For more information, refer to the [relationships](#relationships). + + ## New Resources + + The V3 API introduces new resources that are not available on the V2 API. Below are brief descriptions of these resources. This is not intended to be an exhaustive list and may not be updated as new resources are added to V3. + + **Note:** Some of these resources may still be experimental and are subject to change or removal without warning. For up to date information on which resources are still experimental see [Experimental Resources](#experimental-resources). + + ### App Features + + App features support enabling/disabling behaviors for an individual app. + + Read more about the [app feature resource](#app-features). + + ### Builds + + Builds increase the flexibility and granularity of control available + to clients crafting stagings workflows. For example: + + - Staging older packages instead of always staging the most recent package + - Staging packages without having to stop an application + - Staging packages to produce droplets without setting them as the current + droplet for an app + - Staging packages into droplets for use in tasks and/or rolling deployments + + Read more about the [builds resource](#builds). + + ### Deployments + + Deployments are objects that manage updates to applications with zero downtime. + + Read more about the [deployments resource](#deployments). + + ### Isolation Segments + + Isolation segments provide dedicated pools of resources to which apps can be deployed to isolate workloads. + + Read more about the [isolation segment resource](#isolation-segments). + + ### Manifests + + Manifests are a method for providing bulk configuration to applications and other resources. + + Read more about the [manifest](#manifests) resource. + + ### Revisions + + Revisions represent code and configuration used by an application at a specific time. The most recent revision for a running application represents the code and configuration currently running in Cloud Foundry. + + Read more about the [revision resource](#revisions). + + ### Service Route Bindings + + There is a new resource `service route binding` that represents a binding between a route and a service instance. + + Creation/Deletion of these bindings is therefore done via that endpoint in v3. + + This resource also supports metadata both in create and update requests. + Audit event of type `audit.service_route_binding.update` is recorded when metadata update is requested. + + It has a nested resource for fetching binding parameters from the broker. Parameters are only set during creation. + + Read more about the [service route binding resource](#service-route-binding). + + ### Sidecars + + Sidecars are additional programs that are run in the same container as a process. + + Read more about the [sidecar resource](#sidecars). + + ### Tasks + + Tasks are one-off jobs that are intended to execute a droplet, stop, and be cleaned up, freeing up resources. + + Examples of this include database migrations and running batch jobs. + + Read more about the [task resource](#tasks). + + ## Changed Resources + + This table shows how V2 resources map to their respective V3 counterparts. Note that some V2 resources have split into multiple V3 resources, and some V2 resources have been combined into a single resource on V3. As these resources are currently under active development, these mappings may change. + + |**V2 Resource(s)**|**V3 Resource(s)**|**Details**| + |---|---|---| + |Apps|Apps, Builds, Droplets, Packages, Processes| + |Buildpacks|Buildpacks| + |Domains, Shared Domains, Private Domains|Domains|[Domains in V3](#domains-in-v3)| + |Environment Variable Groups|Environment Variable Groups| + |Events|Audit Events|[Audit Events in V3](#audit-events-in-v3)| + |Feature Flags|Feature Flags| + |Info|Info|[Info in V3](#info-in-v3) + |Jobs|Jobs| + |Organizations|Organizations| + |Quota Definitions|Organization Quotas|[Organization Quotas in V3](#organization-quotas-in-v3) + |Resource Matches|Resource Matches| + |Routes, Route Mappings|Routes, Destinations|[Routes in V3](#routes-in-v3)| + |Security Groups|Security Groups|[Security Groups in V3](#security-groups-in-v3)| + |Services|Service Offerings|[Service Offerings in V3](#service-offerings-in-v3) + |Service Bindings, Service Keys|Service Keys| + |Service Brokers|Service Brokers|[Service Brokers in V3](#service-brokers-in-v3) + |Service Instances, User-Provided Service Instances|Service Instances| + |Service Plans|Service Plans|[Service Plans in V3](#service-plans-in-v3) + |Service Plan Visibilities|Service Plan Visibility|[Service Plan Visibility in V3](#service-plan-visibility-in-v3) + |Spaces|Spaces| + |Space Quota Definitions|Space Quotas|[Space Quotas in V3](#space-quotas-in-v3) + |Stacks|Stacks| + |Usage Events|Usage Events|[Usage Events in V3](#usage-events-in-v3)| + |Users|Roles, Users|[Users and Roles in V3](#users-and-roles-in-v3)| + + ### Audit Events in V3 + + In V2, these were called "events" (e.g. `/v2/events`). In V3, we adopt the term + "audit events" to better distinguish them from usage events. + + V2 audit events contained information about the "actee" (the resource that the + event affected). V3 audit events refer to the affected resource as the "target". + + V2 audit events had a `timestamp` field. In V3, this field has been renamed to + `created_at` for consistency with other resources. The value is the same. + + In general, V3 audit events contain all of the same information that they + contained in V2, but the JSON is structured a little differently. In particular: + + - The `metadata` field has been renamed to `data`. + - Actor-related fields have been grouped into an object under the `actor` key + (e.g. `actor.type` instead of `actor_type`). + - Actee-related fields have been grouped under the `target` key (e.g. + `target.type` instead of `actee_type`). + + V3 endpoints attempt to report audit events in the same way as V2 endpoints did. + A notable case where this was not possible is for the `audit.app.restage` event. + Read more about [restaging](#restage) in V3. + + Read more about the [audit event resource](#audit-events). + + ### Domains in V3 + + In V2, there were two types of domains exposed via different endpoints: private domains and shared domains. + + In V3, there is only one domain resource. A domain is "private" if it has an "owning organization", which is the organization in which the domain is accessible. This is represented as a relationship to this organization. A domain is "shared" if it doesn't have this relationship. + + Read more about the [domain resource](#domains). + + ### Info in V3 + + In V2, `/v2/info` provides descriptive information about the system and endpoints to external APIs. + + In V3, `/v3/info` only provides descriptive information about the system. + + To access the external APIs in V3, use the root (`/`). + + ### Organization Quotas in V3 + + In V2, `-1` represented an unlimited value for a quota limit. + + In V3, `null` is used to represent an unlimited value. + + The names of the limit fields have changed from V2 to V3. + + |**V2**|**V3**| + |---|---| + non_basic_services_allowed | services.paid_services_allowed + total_services | services.total_service_instances + total_service_keys | services.total_service_keys + total_routes | routes.total_routes + total_reserved_route_ports | routes.total_reserved_ports + total_private_domains | domains.total_domains + memory_limit | apps.total_memory_in_mb + instance_memory_limit | apps.per_process_memory_in_mb + app_instance_limit | apps.total_instances + app_task_limit | apps.per_app_tasks + + Read more about the [organization quota resource](#organization-quotas). + + ### Routes in V3 + + In V2, the route resource represented a URL that could be mapped to an app, and the route mapping resource represented a mapping between a route and an app. + + In V3, these concepts have been collapsed into a single route resource. Now, a route can have one or more "destinations" listed on it. These represent a mapping from the route to a resource that can serve traffic (e.g. a process of an app). + + Read more about [routes, destinations, and ports](#routes). + + ### Security Groups in V3 + + In V2, security groups which apply to _all_ spaces in a Cloud Foundry deployment are termed "default", as in "default for running apps" and "default for staging apps". For example, to apply a default security group to all apps in the running lifecycle, one would `PUT /v2/config/running_security_groups/:guid` + + In V3, security groups which apply to _all_ spaces in a Cloud Foundry deployment are termed "global", as in "globally-enabled running apps" and "globally-enabled staging apps." For example, to apply a security group globally to all apps in the running lifecycle, one would `PATCH /v3/security_groups/:guid` with a body specifying the `globally_enabled` key. See [here](#update-a-security-group) for an example. + + In V2, on creation, one can specify the spaces to which the security group applies, but not whether it applies globally (by default). To set the group globally to all spaces in the foundation one would `PUT /v2/config/running_security_groups/43e0441d-c9c1-4250-b8d5-7fb624379e02`. + + In V3, on creation, one can both specify the spaces to which it applies and also whether it applies globally (to staging and/or running) by specifying the `globally_enabled` key. See [here](#create-a-security-group) for more information. + + In V2, the endpoint to apply a security group to a space only includes the lifecycle ("running" or "staging") explicitly when applying to "staging" ("running" is the default lifecycle). For example, to unbind a security group from the running lifecycle, one would `DELETE /v2/security_groups/:guid/spaces/:space_guid`, from the staging lifecycle, `DELETE /v2/security_groups/:guid/staging_spaces/:space_guid`. + + In V3, the endpoint to apply a security group to a space includes the lifecycle. For example to unbind a security group from the running lifecycle, one would `DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid`. + + ### Service Bindings in V3 + + #### Combining service bindings and service keys + + In v2, two different endpoints `/v2/service_bindings` and `/v2/service_keys` + were used to perform bindings operations for service instances. + + In v3, all service bindings that are not route bindings are performed using the [service credential bindings](#service-credential-binding) resource. + Service credential bindings can be of type `app` when it is a binding between a [service instance](#service-instances) and an [application](#apps) + or `key` when it only retrieves the credentials of the service instance. + The `type` filter can be used to list separately each type. + + The required parameters when [creating](#create-a-service-credential-binding) + a service credential binding are different for each type as defined in the documentation. + + #### Object + + The structure of the service credential binding object follows V3 pattern. + If the type is `app` the object will contain a relationship to the app. + + #### Retrieving service credential bindings details + + The `credentials`, `syslog_drain_url` and `volume_mounts` fields for service credential bindings are not included in the response object of service credential bindings. + `/v3/service_credential_bindings/:guid/details` can be used to retrieve the credentials. + + Read more about the [service credential binding details](#get-a-service-credential-binding-details). + + #### Service key operations + + In v2, all service keys operations were synchronous. + + In v3, all service credential bindings, including those of type `key` are asynchronous if possible. + + #### Response mode + + When operating on service credential bindings of `user-provided` service instances the API will respond synchronously for all operations. + + When operating on service credential bindings of `managed` service instances the API will respond asynchronously and the operation might include communicating to the service broker. Read more about async responses [here](#asynchronous-operations). + + #### Audit events + + Audit events of type `audit.service_key.start_create` and `audit.service_key.start_delete` have been added to track when + an async create or delete `key` service credential binding operation has started. + + Audit events of type `audit.service_binding.update` and `audit.service_key.update` are recorded when metadata update is requested. + + Read more about the [service credential binding resource](#service-credential-binding). + + ### Service Brokers in V3 + + #### Create, Update and Delete + + In V3 these endpoints are now asynchronous. See [asynchronous operations](#asynchronous-operations) and [service broker jobs](#service-broker-jobs) for more information. + + Read more about the [service broker resource](#service-brokers). + + ### Service Instances in V3 + + #### Combining managed and user-provided service instances + + In v2, two different endpoints `/v2/service_instances` and `/v2/user_provided_service_instances` + were used to perform operations on service instances according to their types. + + In v3, all service instance operations are performed using the [service instance](#service-instances) resource, regardless of the type. + Service instances can be of type `managed` when it is an instantiation of a [service offering](#service-offerings) registered with CF + or `user-provided` when it describes an instance of an offering that is not registered with CF. + The `type` filter can be used to separately list each type. + + The required parameters when [creating](#create-a-service-instance) and [updating](#update-a-service-instance) + a service instance are different for each type as defined in their respective documentation. + + #### Object + + The structure of the service instances object as well as some attribute names have changed from V2 to V3. + Each service instance type has type specific fields. Certain fields are omitted when they do not apply to the type of the service instance. + + |**V2**|**V3**| + |---|---| + type valid values `managed_service_instance` and `user_provided_service_instance` | type valid values `managed` and `user-provided` | + entity.service_plan_guid | relationships.service_plan.data.guid | + entity.space_guid | relationships.space.data.guid | + + #### User provided service instance credentials + + The `credentials` field for user provided service instances is not included in the response object of service_instances. + `/v3/service_instances/:guid/credentials` can be used to retrieve the credentials. + + Read more about the [service instance credential](#get-credentials-for-a-user-provided-service-instance). + + #### Response mode + + When operating on service instances of type `user-provided` the API will respond synchronously for all operations. + + When the service instance type is `managed` the API will respond asynchronously and the operation might include communicating to the service broker. Read more about async responses [here](#asynchronous-operations). + + #### Listing bindings + + In v2, there were specific endpoints `/v2/service_instances/:guid/service_bindings`, `/v2/service_instances/:guid/service_keys` + and `/v2/user_provided_service_instances/:guid/service_bindings` to retrieve the service bindings and service keys for managed and user-provided service instances. + + In v3, the [service credential bindings](#list-service-credential-bindings) can be filtered by `service_instance_guids` to retrieve the bindings of any service instance. + + #### Service instance route bindings + + In v2, binding a service instance to a route was done as a relationship request for the service instance. + + In v3, there is a new resource [service route binding](#service-route-bindings) that represents a binding between a route and a service instance. + Creation and deletion of route bindings is therefore done via that endpoint in v3. + + Audit events for route bindings have changed as follows: + + |**V2**|**V3**| + |---|---| + audit.service_instance.bind_route | audit.service_route_binding.start_create (async only)
audit.service_route_binding.create | + audit.service_instance.unbind_route |audit.service_route_binding.start_delete (async only)
audit.service_route_binding.delete | + + Read more about the [service instance resource](#service-instances). + + ### Service Offerings in V3 + + Services resource is now replaced by [service offerings resource](#service-offerings) at `/v3/service_offerings` + + Some services related endpoints nested in other resources have been translated to filters on `service_offerings`, with the advantage that filters accept multiple values and can be combined. + + `GET /v2/organizations/:guid/services` is now `GET /v3/service_offerings?organization_guids=guid`. + + `GET /v2/spaces/:guid/services` is now `GET /v3/service_offerings?space_guids=guid` + + `GET /v2/services/:guid/service_plans` is now a filter on the service plan resource: `GET /v3/service_plans?service_offering_guids=guid`. This link can also be found in the object's `links` section. + + In V2, `service_broker_name` was returned in the response. V3 returns this value only if requested using the [`fields` syntax](#fields). Refer to [service offerings resource](#service-offerings) for further information. A link to the `Service Broker` resource is included in the object's `links` section. + + The structure of the service offering object as well as some attribute names have changed from V2 to V3: + + |**V2**|**V3**| + |---|---| + label | name + active | available + bindable | broker_catalog.features.bindable + extra | shareable, broker_catalog.metadata + unique_id | broker_catalog.id + plan_updateable | broker_catalog.features.plan_updateable + instances_retrievable | broker_catalog.features.instances_retrievable + bindings_retrievable | broker_catalog.features.bindings_retrievable + service_broker_guid | relationships.service_broker.data.guid + + Read more about the [service offering resource](#service-offerings). + + ### Service Plan Visibility in V3 + + `v2/service_plan_visibilities` has been replaced in v3 with a nested resource `v3/service_plans/:guid/visibility` + + This new resource has a `type`, and can have a list of `organizations` a `space` or be of type `public` + + Read more about the [service plan visibility resource](#service-plan-visibility). + + ### Service Plans in V3 + + Some service plans related endpoints nested in other resources have been translated to filters on service plans, with the advantage that filters accept multiple values and can be combined. + + `GET /v2/services/:guid/service_plans` -> `GET /v3/service_plans?service_offering_guids=guid` + + Changing plan visibility to `Public` is not a PUT operation anymore. To change visibility use the [service plan visibility resource](#service-plan-visibility) + + The structure of the service plan object as well as some attribute names have changed from V2 to V3: + + |**V2**|**V3**| + |---|---| + active | available + bindable | broker_catalog.features.bindable + extra | broker_catalog.metadata + public | `visibility_type == 'public'` (see [visibility types](#list-of-visibility-types)) + unique_id | broker_catalog.id + plan_updateable | broker_catalog.features.plan_updateable + service_instances_url | use `service_plan_guids` or `service_plan_names` filter on [service instances resource](#service-instances) + service_url | links.service_offering.href + service_guid | relationships.service_offering.data.guid + + Some filters were renamed and changed to accept a list of values: + + |**V2**|**V3**| + |---|---| + service_guid | service_offering_guids + service_instance_guid | service_instance_guids + service_broker_guid | service_broker_guids + unique_id | broker_catalog_ids + + Read more about the [service plan resource](#service-plans). + + ### Space Quotas in V3 + + In V2, `-1` represented an unlimited value for a quota limit. + + In V3, `null` is used to represent an unlimited value. + + The names of the limit fields have changed from V2 to V3. + + |**V2**|**V3**| + |---|---| + non_basic_services_allowed | services.paid_services_allowed + total_services | services.total_service_instances + total_service_keys | services.total_service_keys + total_routes | routes.total_routes + total_reserved_route_ports | routes.total_reserved_ports + memory_limit | apps.total_memory_in_mb + instance_memory_limit | apps.per_process_memory_in_mb + app_instance_limit | apps.total_instances + app_task_limit | apps.per_app_tasks + + Read more about the [space quota resource](#space-quotas). + + ### Usage Events in V3 + + This section covers changes in both [app usage events](#app-usage-events) and [service usage events](#service-usage-events). + + The V2 `service_guid` field for service usage events is now renamed to `service_offering.guid`. + + The V2 `service_label` field for service usage events is now renamed to `service_offering.label`. + + The V2 `app_guid` field for app usage events is now renamed to `process.guid`. + + The V2 experimental field `parent_app_guid` for app usage events was used to identify a backing V3 app if present. In V3, this field has been renamed to `app.guid` and is no longer experimental. + + ### Users and Roles in V3 + + The user resource remains largely unchanged from the v2 API. On v2, `GET /v2/users` was restricted to admins, and other users needed to use nested endpoints (`GET /v2/organizations/:guid/user` and `GET /v2/spaces/:guid/user`) to view user resources. On v3, those nested endpoints are carried over, but `GET /v3/users` is now available for all users in a similar way to other resources. Note that this does not change what user resources are visible. + + In v2, roles were modeled as associations between organization and space endpoints. In V3, roles have a dedicated resource: `/v3/roles`. This has changed the manner in which roles are assigned. For example, in V2, to assign a user the `org_manager` role, one would `PUT /v2/organizations/:org_guid/managers/:user_id`. In V3, one would `POST /v3/roles` with the role type and relationships to the user and organization. + + In v2, when an Org Manager gives a person an Org or Space role, that person automatically receives Org User status in that org. This is no longer the case in the v3 API. + + Read more about [users](#users) and [roles](#roles). + + ## Deprecated Endpoints + + The specialized `/v2/apps/:guid/restage` endpoint is replaced by the + [builds](#builds) resource. Builds allow finer-grained control and increased + flexibility when staging packages into droplets. The V3 API avoids making + assumptions about which package/droplet to use when staging or running an app + and thus leaves it up to clients. + + ### Restage + + The specialized `/v2/apps/:guid/restage` endpoint is replaced by the [builds](#builds) resource. Builds allow finer-grained + control and increased flexibility when staging packages into droplets. The V3 API avoids making assumptions about which + package/droplet to use when staging or running an app and thus leaves it up to clients. + + #### Replicating Restage + + 1. Get newest READY package for an app: + + ` + GET /v3/packages?app_guids=:app-guid&order_by=-created_at&states=READY + ` + + 2. Stage the package: + + ` + POST /v3/build + ` + + 1. Poll build until the state is `STAGED`: + + ` + GET /v3/builds/build-guid + ` + + 1. Stop the app: + + ` + POST /v3/apps/:guid/actions/stop + ` + + 1. Set the app's current droplet to the build's resulting droplet: + + ` + PATCH /v3/apps/:guid/relationships/current_droplet + ` + + 1. Start app: + + ` + POST /v3/apps/:guid/actions/start + ` + + For a zero-downtime restage, you may wish to use [deployments](#deployments) instead of stopping and starting the app. + + #### Restage Event + + Since the V3 API has no concept of a "restage", the `audit.app.restage` audit + event is no longer reported. Instead, the following events can be tracked: + + Audit Event|Description + ---|--- + audit.build.create | A build is created (staging is initiated) + audit.droplet.create | A droplet is created (staging finishes successfully) + audit.app.stop | Stopping an app is initiated + audit.app.droplet.mapped | A droplet is set as the current droplet for an app + audit.app.start | Starting an app is initiated + audit.app.deployment.create | A deployment is initialized version: latest license: name: Apache 2.0 @@ -11,83 +2084,749 @@ info: url: https://www.cloudfoundry.org/ tags: - name: Admin - description: "Administrative operations for Cloud Foundry platform management." + description: |- + These endpoints are only for admin users. - name: Apps - description: "Apps are top-level objects that link together and contain configuration information for your packages, droplets, processes, tasks, and more." + description: |- + Apps are top-level objects that link together and contain configuration + information for your packages, droplets, processes, tasks, and more. + - name: App Features + description: |- + App features are used to manage whether optional capabilities are enabled for a given application. + + ### Supported app features + + **Note**: SSH must also be [enabled globally](https://docs.cloudfoundry.org/running/config-ssh.html) and on the [space](#space-features). + + Name | Description + ---- | ----------- + **ssh** | Enable SSHing into the app + **revisions** | Enable [versioning](#revisions) of an application + **service-binding-k8s** | Enable k8s service bindings for the app + **file-based-vcap-services** | Enable file-based VCAP service bindings for the app + + ### Service binding files + + By default, service binding details are exposed to an app through the `VCAP_SERVICES` environment variable. Two mutually exclusive app features instead expose them as files on the container's file system. Only one of the two features may be enabled for an app at a time. + + - **file-based-vcap-services** writes the full contents of `VCAP_SERVICES` verbatim to a single file named `vcap_services`. + - **service-binding-k8s** translates each service binding into its own directory of files, as described below. + + #### Translation of VCAP_SERVICES to service binding files + + When **service-binding-k8s** is enabled, the service binding details in `VCAP_SERVICES` are converted into a tree of files, following the [servicebinding.io](https://servicebinding.io/spec/core/1.1.0/#workload-projection) workload-projection specification. The binding's name becomes a directory name, and each of the binding's properties becomes a file within that directory whose contents are the property's value. + + The translation follows these rules: + + - Each binding name must be unique and valid; duplicate or invalid names cause an error. A name must match `[a-z0-9\-.]{1,253}` (per the Kubernetes/servicebinding.io spec). + - The binding's name is used as the directory name; its properties become the file names. + - The `credentials` attribute is a JSON object: each top-level key becomes a file whose content is that key's value. Nested objects and lists are serialized as JSON. + - Reserved attributes may overwrite credential keys of the same name without error. The reserved attributes are: `binding_guid`, `binding_name`, `instance_guid`, `instance_name`, `name`, `label`, `tags`, `plan`, `syslog_drain_url`, `volume_mounts`, `type`, and `provider`. + - All file names must match `[a-z0-9\-._]{1,253}`; an invalid name causes an error. The underscore follows a post-1.1.0 update to the servicebinding.io spec ([commit `b5d6755`](https://github.com/servicebinding/spec/commit/b5d67551d13c8801f6b8a084c70b7167e3fbbe7e)), which is not yet part of a published spec release. + - List values (for example `tags` or `volume_mounts`) are stored as JSON arrays. + - Empty lists and `null` values are omitted - no file is created. + - Cloud Controller always writes a `type` file and a `provider` file, both set to the service label. + - If the total byte size (file paths plus contents) exceeds **1,000,000 bytes**, an error is raised. + + ##### Examples + + The following examples illustrate individual translation rules, showing only the properties relevant to each rule. + + Nested and list credentials are serialized as JSON. + + Input (`VCAP_SERVICES`): + + ```json + { + "foo": [ + { + "name": "foo", + "credentials": { + "simple": "value", + "deeply": { + "nested": "value" + }, + "list": ["v", "a", "l", "u", "e"] + } + } + ] + } + ``` + + Output (service binding files): + + ``` + foo/name: foo + foo/simple: value + foo/deeply: {"nested":"value"} + foo/list: ["v","a","l","u","e"] + ``` + + A reserved attribute overwrites a credential key (the `name` credential is dropped in favor of the binding's `name`). + + Input (`VCAP_SERVICES`): + + ```json + { + "foo": [ + { + "name": "foo", + "credentials": { + "name": "user", + "secret": "password" + } + } + ] + } + ``` + + Output (service binding files): + + ``` + foo/name: foo + foo/secret: password + ``` + + `null` and empty values are omitted. + + Input (`VCAP_SERVICES`): + + ```json + { + "foo": [ + { + "name": "foo", + "binding_guid": "45436ca8-0a7c-45e3-9439-ca1b44db7a2b", + "syslog_drain_url": null, + "volume_mounts": [] + } + ] + } + ``` + + Output (service binding files): + + ``` + foo/name: foo + foo/binding_guid: 45436ca8-0a7c-45e3-9439-ca1b44db7a2b + ``` - name: App Usage Events - description: "App usage events are a record of changes in the usage of apps and tasks." + description: |- + App usage events are a record of changes in the usage of apps and tasks. + Examples include starting an application, scaling an application (from, say, one + to three instances), and stopping an application. + + Usage events are typically used by billing and chargeback applications. - name: Audit Events - description: "Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions." + description: |- + Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions. + + For more information, see the [Cloud Foundry docs](https://docs.cloudfoundry.org/running/managing-cf/audit-events.html). + + #### Audit Event Types + + ##### App lifecycle + - `audit.app.apply_manifest` + - `audit.app.build.create` + - `audit.app.build.failed` + - `audit.app.build.staged` + - `audit.app.copy-bits` + - `audit.app.create` + - `audit.app.delete-request` + - `audit.app.deployment.cancel` + - `audit.app.deployment.create` + - `audit.app.deployment.continue` + - `audit.app.droplet.create` + - `audit.app.droplet.delete` + - `audit.app.droplet.download` + - `audit.app.droplet.mapped` + - `audit.app.droplet.upload` + - `audit.app.environment.show` + - `audit.app.environment_variables.show` + - `audit.app.map-route` + - `audit.app.package.create` + - `audit.app.package.delete` + - `audit.app.package.download` + - `audit.app.package.upload` + - `audit.app.process.crash` + - `audit.app.process.create` + - `audit.app.process.delete` + - `audit.app.process.ready` + - `audit.app.process.not-ready` + - `audit.app.process.rescheduling` + - `audit.app.process.scale` + - `audit.app.process.terminate_instance` + - `audit.app.process.update` + - `audit.app.restage` + - `audit.app.restart` + - `audit.app.revision.create` + - `audit.app.revision.environment_variables.show` + - `audit.app.ssh-authorized` + - `audit.app.ssh-unauthorized` + - `audit.app.start` + - `audit.app.stop` + - `audit.app.task.cancel` + - `audit.app.task.create` + - `audit.app.unmap-route` + - `audit.app.update` + - `audit.app.upload-bits` + + ##### Buildpack lifecycle + - `audit.buildpack.create` + - `audit.buildpack.delete` + - `audit.buildpack.update` + - `audit.buildpack.upload` + + ##### Organization lifecycle + - `audit.organization.create` + - `audit.organization.delete-request` + - `audit.organization.update` + + ##### Organization_quota lifecycle + - `audit.organization_quota.apply` + - `audit.organization_quota.create` + - `audit.organization_quota.delete` + - `audit.organization_quota.update` + + ##### Route lifecycle + - `audit.route.create` + - `audit.route.delete-request` + - `audit.route.share` + - `audit.route.transfer-owner` + - `audit.route.unshare` + - `audit.route.update` + + ##### Route_policy lifecycle + - `audit.route_policy.create` + - `audit.route_policy.delete` + - `audit.route_policy.update` + + ##### Service lifecycle + - `audit.service.create` + - `audit.service.delete` + - `audit.service.update` + + ##### Service_binding lifecycle + - `audit.service_binding.create` + - `audit.service_binding.delete` + - `audit.service_binding.show` + - `audit.service_binding.start_create` + - `audit.service_binding.start_delete` + - `audit.service_binding.update` + + ##### Service_broker lifecycle + - `audit.service_broker.create` + - `audit.service_broker.delete` + - `audit.service_broker.update` + + ##### Service_dashboard_client lifecycle + - `audit.service_dashboard_client.create` + - `audit.service_dashboard_client.delete` + + ##### Service_instance lifecycle + - `audit.service_instance.bind_route` + - `audit.service_instance.create` + - `audit.service_instance.delete` + - `audit.service_instance.purge` + - `audit.service_instance.share` + - `audit.service_instance.show` + - `audit.service_instance.start_create` + - `audit.service_instance.start_delete` + - `audit.service_instance.start_update` + - `audit.service_instance.unbind_route` + - `audit.service_instance.unshare` + - `audit.service_instance.update` + + ##### Service_key lifecycle + - `audit.service_key.create` + - `audit.service_key.delete` + - `audit.service_key.show` + - `audit.service_key.start_create` + - `audit.service_key.start_delete` + - `audit.service_key.update` + + ##### Service_plan lifecycle + - `audit.service_plan.create` + - `audit.service_plan.delete` + - `audit.service_plan.update` + + ##### Service_plan_visibility lifecycle + - `audit.service_plan_visibility.create` + - `audit.service_plan_visibility.delete` + - `audit.service_plan_visibility.update` + + ##### Service_route_binding lifecycle + - `audit.service_route_binding.create` + - `audit.service_route_binding.delete` + - `audit.service_route_binding.start_create` + - `audit.service_route_binding.start_delete` + - `audit.service_route_binding.update` + + ##### Space lifecycle + - `audit.space.create` + - `audit.space.delete-request` + - `audit.space.update` + + ##### Space_quota lifecycle + - `audit.space_quota.apply` + - `audit.space_quota.create` + - `audit.space_quota.delete` + - `audit.space_quota.remove` + - `audit.space_quota.update` + + ##### Stack lifecycle + - `audit.stack.create` + - `audit.stack.delete` + - `audit.stack.update` + + ##### User lifecycle + - `audit.user.organization_auditor_add` + - `audit.user.organization_auditor_remove` + - `audit.user.organization_billing_manager_add` + - `audit.user.organization_billing_manager_remove` + - `audit.user.organization_manager_add` + - `audit.user.organization_manager_remove` + - `audit.user.organization_user_add` + - `audit.user.organization_user_remove` + - `audit.user.space_auditor_add` + - `audit.user.space_auditor_remove` + - `audit.user.space_developer_add` + - `audit.user.space_developer_remove` + - `audit.user.space_manager_add` + - `audit.user.space_manager_remove` + - `audit.user.space_supporter_add` + - `audit.user.space_supporter_remove` + + ##### User_provided_service_instance lifecycle + - `audit.user_provided_service_instance.create` + - `audit.user_provided_service_instance.delete` + - `audit.user_provided_service_instance.show` + - `audit.user_provided_service_instance.update` + + ##### Special events + - `app.crash` + - `blob.remove_orphan` - name: Builds - description: "Builds represent the process of staging an application package." + description: |- + Builds represent the process of staging an application package. There are two types + ([lifecycles](#lifecycles)) of builds: buildpack and docker. + + After an [application](#apps) is created and [packages](#packages) are uploaded, a build + resource can be created to initiate the staging process. A successful build results in a + [droplet](#droplets). - name: Buildpacks - description: "Buildpacks are used during a build to download external dependencies and transform a package into an executable droplet." + description: |- + Buildpacks are used during a [build][builds] + to download external dependencies + and transform a [package][packages] + into an executable [droplet][droplets]. + In this way, buildpacks are a pluggable extension to Cloud Foundry + that enable CF to run different languages and frameworks. + Buildpacks will automatically detect if they support an application. + Buildpacks can also be explicitly specified on [apps][] and [builds][]. + + [apps]: #apps + [builds]: #builds + [droplets]: #droplets + [packages]: #packages - name: Deployments - description: "Deployments are objects that manage updates to applications with zero downtime." + description: |- + Deployments are objects that manage updates to applications with zero downtime. + + They can either: + + * Manage updating an app's [droplet](#droplets) directly after an application package is staged + + * Roll an app back to a specific [revision](#revisions) along with its associated droplet + + Deployments are different than the traditional method of pushing app updates which performs start/stop deployments. + + Deployment strategies supported: + + * [Rolling deployments](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html) allows for + applications to be deployed without incurring downtime by gradually rolling out instances. Max-in-flight can be configured + to specify how many instances are rolled out simultaneously. + + * [Canary deployments](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html#canary-deployment-process) deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via the [continue action](#continue-a-deployment). The deployment then continues like a rolling deployment. This feature is experimental and is subject to change. - name: Domains - description: "Domains represent a fully qualified domain name that is used for application routes." + 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. - name: Droplets - description: "Droplets are the result of staging an application package." + description: |- + Droplets are the result of staging an application package. There are two types + (lifecycles) of droplets: buildpack and docker. In the case of the buildpacks, + the droplet contains the bits produced by the buildpack, typically application + code and dependencies. + + After an application is created and packages are uploaded, a droplet must be + created via a [build](#builds) in order for an application to be deployed or tasks to be run. + The current droplet [must be assigned](#set-current-droplet) to an + application before it may be started. When [tasks are created](#create-a-task), + they either use a specific droplet guid, or use the current droplet assigned to an application. - name: Environment Variable Groups - description: "There are two types of environment variable groups: running and staging." + description: |- + There are two types of environment variable groups: running and staging. They are designed to allow platform operators/admins to manage environment variables across all apps in a foundation. + + Variables in a **running** environment variable group will be injected into all **running app containers**. + + Variables in a **staging** environment variable group will be injected into the **staging container** for all apps while they are being staged. - name: Feature Flags - description: "Feature flags are runtime flags that enable or disable functionality on the API." + description: |- + Feature flags are runtime flags that enable or disable functionality on the API. + + ### List of feature flags + + | Name | Default | Description | + | ---- | ------- | ----------- | + | `app_bits_upload` | `true` | When enabled, space developers can upload app bits. When disabled, only admin users can upload app bits. | + | `app_scaling` | `true` | When enabled, space developers can perform scaling operations (i.e. change memory, disk, log rate, or instances). When disabled, only admins can perform scaling operations. | + | `diego_cnb (experimental)` | `false` | When enabled, the staging process using Cloud Native Buildpacks is supported. | + | `diego_docker` | `false` | When enabled, Docker applications are supported by Diego. When disabled, Docker applications will stop running. It will still be possible to stop and delete them and update their configurations. | + | `env_var_visibility` | `true` | When enabled, all users can see their environment variables. When disabled, no users can see environment variables. | + | `hash_based_routing` | `false` | When enabled, the `hash`, `hash_header`, and `hash_balance` route options may be set on a route to enable hash-based load balancing. When disabled, those route options are rejected. | + | `hide_marketplace_from_unauthenticated_users` | `false` | When enabled, service offerings available in the marketplace will be hidden from unauthenticated users. When disabled, unauthenticated users will be able to see the service offerings available in the marketplace. | + | `private_domain_creation` | `true` | When enabled, an organization manager can create private domains for that organization. When disabled, only admin users can create private domains. | + | `resource_matching` | `true` | When enabled, any user can create resource matches. When disabled, the [resource match endpoint](#resource-matches) always returns an empty array of matches. The [package upload endpoint](#upload-package-bits) will not cache any uploaded packages for resource matching. | + | `route_creation` | `true` | When enabled, a space developer can create routes in a space. When disabled, only admin users can create routes. | + | `route_sharing (experimental)` | `false` | When enabled, Space Developers can share routes between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share routes between two spaces. | + | `service_instance_creation` | `true` | When enabled, a space developer can create service instances in a space. When disabled, only admin users can create service instances. | + | `service_instance_sharing` | `false` | When enabled, Space Developers can share service instances between two spaces (even across orgs!) in which they have the Space Developer role. When disabled, Space Developers cannot share service instances between two spaces. | + | `set_roles_by_username` | `true` | When enabled, Org Managers or Space Managers can add access roles by username. In order for this feature to be enabled the CF operator must:
1) Enable the `/ids/users/` endpoint for UAA
2) Create a UAA `cloud_controller_username_lookup` client with the `scim.userids` authority | + | `space_developer_env_var_visibility` | `true` | When enabled, space developers can perform a get on the /v2/apps/:guid/env endpoint, and both space developers and space supporters can perform a get on the /v3/apps/:guid/env and /v3/apps/:guid/environment_variables endpoints. When disabled, neither space developers nor space supporters can access these endpoints. | + | `space_scoped_private_broker_creation` | `true` | When enabled, space developers can create space scoped private brokers. When disabled, only admin users can create create space scoped private brokers. | + | `task_creation` | `true` | When enabled, space developers can create tasks. When disabled, only admin users can create tasks. | + | `unset_roles_by_username` | `true` | When enabled, Org Managers or Space Managers can remove access roles by username. In order for this feature to be enabled the CF operator must:
1) Enable the `/ids/users/` endpoint for UAA
2) Create a UAA `cloud_controller_username_lookup` client with the `scim.userids` authority | + | `user_org_creation` | `false` | When enabled, any user can create an organization via the API. When disabled, only admin users can create organizations via the API. | + - name: Info - description: "Info endpoints expose Cloud Controller configuration information." - - name: Internal - description: "Internal endpoints for system monitoring and metrics." + description: |- + Info endpoints expose Cloud Controller configuration information. - name: Isolation Segments - description: "Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads." + description: |- + Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads. - name: Jobs - description: "Jobs are created by the platform when performing certain asynchronous actions." + description: |- + Jobs are created by the platform when performing certain asynchronous actions. - name: Manifests - description: "A manifest is a method for applying bulk configurations to apps and their underlying processes." + description: |- + ## Manifests - name: Organizations - description: "An org is a development account that an individual or multiple collaborators can own and use." + description: |- + An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains. - name: Organization Quotas - description: "Organization quotas are named sets of memory, log rate, service, and instance usage quotas." + description: |- + Organization quotas are named sets of memory, log rate, service, and instance usage quotas. For example, one organization quota might allow up to 10 services, 10 routes, and 2 GB of RAM, while another might offer 100 services, 100 routes, and 10 GB of RAM. + + An organization has exactly one organization quota. If not specifically assigned a quota, it will have the default quota. + + For more information, see the [Cloud Foundry docs](https://docs.cloudfoundry.org/adminguide/quota-plans.html). - name: Packages - description: "A package is an application’s ‘source code’; either raw bits for your application or a pointer to these bits." + description: |- + A package is an application's 'source code'; either raw bits for your application or a pointer to these bits. + + In Cloud Foundry, packages are staged to produce an executable Droplet. We currently support raw bits and Docker packages. - name: Processes - description: "Processes define the runnable units of an app." + description: |- + Processes define the runnable units of an app. An app can have multiple process types, each with differing commands and scale. + Processes for an app are defined by the buildpack used to stage the app and can be customized by including a [Procfile](#procfiles) in the application source. + + #### Web process type + * By default, a newly created app will come with one instance of the `web` process and all other process types are scaled to zero + * Scale the `web` process to zero if it is not required for your app + * Unless otherwise specified, all routes will be mapped to the `web` process by default - name: Resource Matches - description: "Resource Matches are used to determine if a resource has been previously uploaded to the Cloud Controller." + description: |- + This endpoint matches given resource SHA-1/file size pairs against the Cloud Controller cache + and reports the subset that describes already cached files. + This is usually used to avoid uploading duplicate files + when pushing an app which has only been partially changed. + The `path` and `mode` fields are not used when matching. + + When [uploading package bits](#upload-package-bits), + the response from this endpoint should be used as the `resources` form field. + As such, it is useful to include the `path` and `mode` fields for each resource + even though they are not used when determining a resource match. + + Cloud Foundry operators may set minimum/maximum file sizes to match against. + If the file size provided is outside this range, + it will not be matched against. + + If the `resource_matching` [feature flag](#the-feature-flag-object) is disabled, + resource matching will always return an empty array. - name: Revisions - description: "Revisions represent code used by an application at a specific time." + description: |- + Revisions represent code used by an application at a specific time. The most recent revision for a running application represents code and configuration currently running in Cloud Foundry. Revisions are not created for Tasks. + + Revision are created when the following is changed: + + * A new droplet is deployed for an app + + * An app is deployed with new environment variables + + * The app is deployed with a new or changed custom start command + + * An app rolls back to a prior revision + + Each time a new revision is created the reason(s) for the revisions creation will be appended to its description field. + + By default the cloud foundry API retains at most 100 revisions per app. - name: Roles - description: "Roles are used to control access to resources." + description: |- + Roles control access to resources in organizations and spaces. + Roles are assigned to users. + + For example, a user with the `space_developer` role is able to push + applications to their space. A `space_manager` user can also add roles to users + within that space (e.g. making a user a `space_auditor`). An + `organization_manager` has wide-reaching privileges, able to create & delete + spaces, and assign & unassign roles to users. + + ### Valid role types + - `organization_user` + - `organization_auditor` + - `organization_manager` + - `organization_billing_manager` + - `space_auditor` + - `space_developer` + - `space_manager` + - `space_supporter` + * Users with only the space supporter role are not authorized to use the **V2** API - name: Root - description: "Root API endpoints that provide entry points and API information." + description: |- + These endpoints link to other resources, endpoints, and external services that are relevant to API clients. + - name: Route Policies + 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.** - name: Routes - description: "Routes are used to map a URL to an app." + description: |- + Routes are addresses that direct matched network traffic to one or more destinations. Each route is based on a domain name with additional matching criteria (host (subdomain), path, etc). Matched traffic will be distributed across all destinations, based on their configuration (round-robin by default). - name: Security Groups - description: "Security groups are used to control access to apps." + description: |- + Security groups are collections of egress traffic rules that can be applied to the staging or running state of applications. + + Security groups can either be applied globally or at the space-level. + + Security groups can only allow (whitelist) traffic. They cannot be used to disallow (blacklist) traffic. + + IPv6 security groups can be configured if `cc.enable_ipv6` is set to `true`. - name: Service Brokers - description: "Service brokers are used to manage services." - - name: Service Credential Bindings - description: "Service credential bindings are used to bind a service instance to an app." - - name: Service Instances - description: "Service instances are instances of a service." + description: |- + Service brokers manage the lifecycle of services. On behalf of users, Cloud Controller will interact with service brokers to provision, get access to and manage access to the service offerings and plans they offer. + + Admins can create and manage service brokers that are globally available, i.e., the service broker and its associated resources (service offerings and plans) can be made available to all users. + + Space Developers can create and manage space-scoped service brokers. A space-scoped broker and its associated resources will only be available in the space the service broker was created. + + ### Service broker jobs + + CRUD operations for service brokers are asynchronous. `create`, `update` and `delete` endpoints include a job URL in the `Location` header of the HTTP response. + + These jobs are the only source of information about the progress of the operation. Therefore, the job must be polled to find out when the process ends and if it was successful. + There is no mechanism to link a service broker with its jobs, apart from the `Location` header in the API response. + + When a failure occurs during a create job, the service broker won't be usable. It will still be included in the `GET` endpoints responses, hence the importance of querying the job to find out the end status. + + When updating a service broker, catalog changes will be rolled-back in the event of the job failing. The service broker catalog will remain unchanged with no indication that the update operation failed. Querying the job will provide such information. - name: Service Offerings - description: "Service offerings are services that are available to be used." + description: |- + Service offerings represent the services offered by service brokers. + A service broker will have one or more service offerings. + A service offering will have one or more service plans. + Service offerings and service plans are created and updated when a service broker is registered or updated. + + ### Visibility of service offerings + + This table shows the service offerings that different roles can see. + The service offerings that a user can see relate to their space and organization roles, + regardless of which space or organization is being targeted. + + A service offering can be seen when at least one of its service plans can be seen. + Service plans may be configured to be `public`, + or they may be configured with a relationship to a restricted list of organizations. + + Service offerings and service plans from a space-scoped service broker cannot have their visibility configured. + They are only visible to members of that space. + + Role | Public plans | Restricted plans | From space-scoped service brokers + --- | --- | --- | --- + Admin | All | All | All + Admin Read | All | All | All + Global Auditor | All | All | All + Org Manager | All | In organisation | None + Org Auditor | All | In organisation | None + Org Billing | All | In organisation | None + Space Manager | All | In organisation | In space + Space Developer | All | In organisation | In space + Space Auditor | All | In organisation | In space + Unauthenticated | All* | None | None + + *Unless the `hide_marketplace_from_unauthenticated_users` feature flag is `true` - name: Service Plans - description: "Service plans are plans for a service." + description: |- + Service plans represent the service plans offered by a service offering. + A service offering will have one or more service plans. + Service offerings and service plans are created and updated when a service broker is registered or updated. + - name: Service Plan Visibility + description: |- + Service plan visibility is used to manage whether a role has access to a given service plan and its service offering. + + ### List of visibility types + + Name | Description + ---- | ----------- + **public** | Everyone, including unauthenticated users can see the service plan + **admin** | Only Admin, Admin Read-Only and Global Auditor can see the service plan + **organization** | Restricted to members of a set of organizations + **space** | Restricted to members of a space; only possible if the plan comes from a space-scoped service broker + - name: Service Instances + description: |- + An instantiation of a service. + + Service instances can be of type `managed` when it is an instantiation of a [service offering](#service-offerings) registered with CF + or `user-provided` when it describes an instance of an offering that is not registered with CF. + - name: Service Credential Bindings + description: |- + Service credential bindings are used to make the details of the connection to a service instance available to an app or a developer. + + Service credential bindings can be of type `app` or `key`. + + A service credential binding is of type `app` when it is a binding between a [service instance](#service-instances) and an [application](#apps). + Not all services support this binding, as some services deliver value to users directly without integration with an application. + Field `broker_catalog.features.bindable` from [service plan](#the-service-plan-object) of the service instance can be used to determine if it is bindable. + + A service credential binding is of type `key` when it only retrieves the details of the service instance and makes them available to the developer. - name: Service Route Bindings - description: "Service route bindings are used to bind a route to a service instance." + description: |- + Service route bindings are relations between a service instance and a route. + + Not all service instances support route binding. + In order to bind to a managed service instance, the service instance should be created from a service offering that has requires route forwarding (`requires=[route_forwarding]`). + In order to bind to a user-provided service instance, the service instance must have `route_service_url` set. - name: Service Usage Events - description: "Service usage events are a record of changes in the usage of services." + description: |- + Service usage events are a record of changes in the usage of services. For + example, service usage events are recorded when a service instance is created, + updated, and deleted. They may contain information about the service instance in + question and the associated space, service broker, and service offering. + + Usage events are typically used by billing and chargeback applications. - name: Sidecars - description: "Sidecars are used to run a process alongside an app." + description: |- + Sidecars are additional operating system processes that are run in the same container as a [process](#processes). + + #### Use cases for sidecars + + Sidecars are useful for any app processes that need to communicate with another within the same container or are otherwise dependent on each other. Some use cases are: + + - Two or more processes that require access to a shared file + - An Application Performance Monitoring (APM) tool that attaches to a dependent app's processes + - Two or more processes that communicate via a local socket + + #### Steps to create a sidecar + The recommended way to create sidecars for your app is with a [manifest](#manifests). + + ```yaml + sidecars: + - name: authenticator + process_types: [ 'web', 'worker' ] + command: bundle exec run-authenticator + - name: performance monitor + process_types: [ 'web' ] + command: bundle exec run-performance-monitor + memory: 128M + ``` + + - **name** is a user defined identifier (unique per app) + - **process_types** is a list of app processes the sidecar will attach to. You can attach multiple sidecars to each process type your app uses + - **command** is the command used to start the sidecar + - **memory** is the memory reserved for the sidecar[1] + + 1 Applies for Java apps. If you do not reserve memory for the sidecar, the JVM will consume all of the memory in the app container. This value must be less thatn the process' reserved memory. + + #### Current limitations + - Start and stop order of app processes and their sidecars is undefined + - App processes and sidecar processes are codependent: if either crashes or exits, the other will as well + - Sidecars are currently not independently scalable (memory / disk) and share resources with the main app process and other sidecars within that container + - Sidecars only support PID based health checks; HTTP health-checks for sidecars are not currently supported + - This has only been tested on Linux based systems - name: Spaces - description: "Spaces are used to group apps and services." + description: |- + Every application and service is scoped to a space. Each org contains at least one space. A space provides users with access to a shared location for application development, deployment, and maintenance. + - name: Space Features + description: |- + Space features are used to manage whether optional capabilities are enabled for + a given space. + + Currently, the only space feature is SSH (`ssh`), which controls whether + applications in the space may be accessed via SSH. + + **Note**: SSH must also be [enabled globally](https://docs.cloudfoundry.org/running/config-ssh.html) and on the [app](#supported-app-features). - name: Space Quotas - description: "Space quotas are named sets of memory, log rate, service, and instance usage quotas." + description: |- + Space quotas are named sets of quotas. Space quota names are unique within an organization. For example, an organization may only have one space quota named "production", but two organizations may have two distinct space quotas, both named "production". + + Only one space quota may be applied to a given space at any given time. + + Space quotas cannot be used to bypass organization quotas. When the organization's quota and the space's quota specify a different values for a given resource, the more restrictive of the two is used. In the event of permissions, the more restrictive permission is used. - name: Stacks - description: "Stacks are used to specify the operating system and runtime environment for an app." + description: |- + Stacks are the base operating system and file system that your application will execute in. + A stack is how you configure applications to run against different operating systems + (like Windows or Linux) + and different versions of those operating systems + (like Windows 2012 or Windows 2016). + + An application's [lifecycle](#lifecycles) will specify which stack to execute the application in. + Buildpacks can also be associated with a particular stack if they contain stack-specific logic. + An application will automatically use buildpacks associated with the application's configured stack. + + Stacks are not used for apps with a [Docker lifecycle](#docker-lifecycle). + + Operators control stack availability through state management. The following states determine how a stack can be used: + + *ACTIVE*: Default state. The stack is fully available for all operations. + + *DEPRECATED*: The stack is nearing end-of-life. It remains fully functional, + but users should migrate to an ACTIVE stack. + + *RESTRICTED*: A transitional state typically applied before deprecation or disabling. + New application creation is blocked; existing deployments continue to operate normally. + + *DISABLED*: The stack has reached end-of-life. New application creation and restaging are prohibited. + Running applications remain available. - name: Tasks - description: "Tasks are one-off commands that can be run against an app." + description: |- + Tasks are one-off jobs that are intended to perform a task, stop, and be cleaned up, freeing up resources. + + Examples of this include database migrations, sending things, and batch jobs. - name: Users - description: "Users are the users of the Cloud Foundry platform." + description: |- + The user resource is used to manage access to organizations, spaces, and other + resources within Cloud Foundry. Cloud Controller is not the ultimate authority + on the users in the Cloud Foundry system; UAA and its configured identity + providers determine which users are able to sign in to Cloud Foundry. + + To be functional, Cloud Controller users must "shadow" a corresponding user or + client in UAA. The Cloud Controller user resource's guid should match either a + UAA user or a UAA client id. However, Cloud Controller does not enforce that + a user's guid is a valid UAA user or client id. + + Users can be assigned roles, which give them privileges to perform actions + within a given context. For example, the Space Developer role grants a user + permission to manage apps and services in a space (e.g. to push apps, scale + apps, delete apps). security: - oauth: - cloud_controller.read @@ -464,6 +3203,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/AdminClearBuildpackCache.yaml b/docs/openapi/apis/cf/latest/paths/AdminClearBuildpackCache.yaml index 53fffbc273c..93c35457e33 100644 --- a/docs/openapi/apis/cf/latest/paths/AdminClearBuildpackCache.yaml +++ b/docs/openapi/apis/cf/latest/paths/AdminClearBuildpackCache.yaml @@ -1,6 +1,9 @@ post: - summary: Clear the buildpack cache - description: This endpoint will delete all of the existing buildpack caches in the blobstore. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. An admin who wants to decrease the size of their blobstore could use this endpoint to delete unnecessary blobs. + summary: Clear buildpack cache + description: |- + This endpoint will delete all of the existing buildpack caches in the blobstore. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. An admin who wants to decrease the size of their blobstore could use this endpoint to delete unnecessary blobs. + + **Permitted roles:** Admin operationId: clearBuildpackCache tags: - Admin @@ -13,6 +16,8 @@ post: schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/c33a5caf-77e0-4d6e-b587-5555d339bc9a '401': $ref: '../components/responses/Unauthorized.yaml' '403': diff --git a/docs/openapi/apis/cf/latest/paths/AppUsageEvents.yaml b/docs/openapi/apis/cf/latest/paths/AppUsageEvents.yaml index 754297f1114..469bb34d64c 100644 --- a/docs/openapi/apis/cf/latest/paths/AppUsageEvents.yaml +++ b/docs/openapi/apis/cf/latest/paths/AppUsageEvents.yaml @@ -1,21 +1,34 @@ /v3/app_usage_events: get: summary: List app usage events - description: Retrieve all app usage events. + description: |- + Retrieve all app usage events the user has access to. + + **Permitted roles:** All Roles operationId: listAppUsageEvents tags: - App Usage Events 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 + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid value is `created_at` - name: after_guid in: query + required: false schema: type: string description: Filters out events before and including the event with the given guid - name: guids in: query + required: false schema: type: array items: @@ -37,11 +50,11 @@ total_results: 2 total_pages: 2 first: - href: https://api.example.org<%= path %>?page=1&per_page=1 + href: https://api.example.org/v3/app_usage_events?page=1&per_page=1 last: - href: https://api.example.org<%= path %>?page=2&per_page=1 + href: https://api.example.org/v3/app_usage_events?page=2&per_page=1 next: - href: https://api.example.org<%= path %>?page=2&per_page=1 + href: https://api.example.org/v3/app_usage_events?page=2&per_page=1 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 @@ -97,12 +110,21 @@ /v3/app_usage_events/{guid}: get: summary: Get an app usage event - description: Retrieve a specific app usage event. + description: |- + Retrieve an app usage event. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor operationId: getAppUsageEvent tags: - App Usage Events parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app usage event responses: '200': description: OK @@ -156,17 +178,23 @@ post: summary: Purge and seed app usage events description: |- - Destroys all existing events. Populates new usage events, one for each - started app. All populated events will have a created_at value of - current time. There is the potential race condition if apps are - currently being started, stopped, or scaled. The seeded usage events - will have the same guid as the app. + Destroys all existing events. Populates new usage events, one for each started app. All populated events will have a `created_at` value of current time. There is the potential race condition if apps are currently being started, stopped, or scaled. The seeded usage events will have the same guid as the app. + + **Permitted roles:** Admin operationId: purgeAndSeedAppUsageEvents tags: - App Usage Events responses: '200': description: OK + content: + application/json: + schema: + type: object + examples: + default: + summary: default + value: {} '400': $ref: ../components/responses/BadRequest.yaml '401': diff --git a/docs/openapi/apis/cf/latest/paths/Apps.yaml b/docs/openapi/apis/cf/latest/paths/Apps.yaml index 193319a8f62..24fa427b78f 100644 --- a/docs/openapi/apis/cf/latest/paths/Apps.yaml +++ b/docs/openapi/apis/cf/latest/paths/Apps.yaml @@ -1,63 +1,87 @@ /v3/apps: get: summary: List apps - description: Retrieve all apps the user has access to. + description: |- + Retrieve all apps the user has access to. + + **Permitted roles:** All Roles operationId: listApps tags: - Apps 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 + - state + - -state + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`, `name`, `state` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app GUIDs to filter by + description: Comma-delimited list of app guids to filter by - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app names to filter by + description: Comma-delimited list of app names to filter by (case-insensitive) - name: space_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of space GUIDs to filter by + description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false 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 - name: stacks in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of stack names to filter by + description: Comma-delimited list of stack names to filter by (case-sensitive) - name: lifecycle_type in: query + required: false schema: type: string enum: - buildpack - cnb - docker - description: Lifecycle type to filter by + description: '[Lifecycle](#lifecycles) type to filter by; valid values are `buildpack`, `cnb`, `docker`' - name: include in: query + required: false schema: type: array items: @@ -65,7 +89,7 @@ enum: - space - space.organization - description: Optionally include a list of unique related resources in the response + description: Optionally include a list of unique related resources in the response; valid values are `space` and `space.organization` responses: '200': description: OK @@ -81,14 +105,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/apps?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/apps?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/apps?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' @@ -102,10 +126,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -138,7 +162,7 @@ metadata: labels: {} annotations: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 02b4ec9b-94c7-4468-9c23-4e906191a0f8 name: my_app2 state: STOPPED created_at: '1970-01-01T00:00:02Z' @@ -152,39 +176,39 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - droplet: + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 + current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8 + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8 space: href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 processes: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/processes packages: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/packages environment_variables: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/environment_variables current_droplet: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets/current droplets: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/droplets tasks: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/tasks start: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/start method: POST stop: - href: https://api.example.org/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/actions/stop method: POST revisions: - href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions deployed_revisions: - href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/revisions/deployed features: - href: https://api.example.org//02b4ec9b-94c7-4468-9c23-4e906191a0f8/features + href: https://api.example.org/v3/apps/02b4ec9b-94c7-4468-9c23-4e906191a0f8/features metadata: labels: {} annotations: {} @@ -206,7 +230,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create an app - description: Creates a new app. + description: |- + Creates a new app. + + **Permitted roles:** Admin, Space Developer operationId: createApp tags: - Apps @@ -223,7 +250,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app state: STOPPED created_at: '2016-03-17T21:41:30Z' @@ -237,10 +264,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -289,7 +316,20 @@ '401': $ref: ../components/responses/Unauthorized.yaml '403': - $ref: ../components/responses/Forbidden.yaml + description: Forbidden + content: + application/json: + schema: + $ref: ../components/schemas/Errors.yaml + examples: + feature_disabled: + summary: CF-FeatureDisabled + description: Some [feature flag](#list-of-feature-flags) must be enabled by the Cloud Foundry admin in order to push the app as is. The `detail` message should contain information on which feature is disabled. + value: + errors: + - code: 330002 + title: CF-FeatureDisabled + detail: 'Feature Disabled: diego_docker' '409': $ref: ../components/responses/Conflict.yaml '422': @@ -300,17 +340,13 @@ $ref: ../components/schemas/Errors.yaml examples: uniqueness_error: + summary: CF-UniquenessError + description: The given app name is already taken in the targeted space value: errors: - code: 10016 title: CF-UniquenessError detail: The given app name is already taken in the targeted space - feature_disabled: - value: - errors: - - code: 330002 - title: CF-FeatureDisabled - detail: Some feature flag must be enabled by the Cloud Foundry admin in order to push the app as is. '500': $ref: ../components/responses/500.yaml '503': @@ -318,7 +354,10 @@ /v3/apps/{guid}: get: summary: Get an app - description: Retrieve a specific app. + description: |- + Retrieve a specific app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getApp tags: - Apps @@ -326,6 +365,7 @@ - $ref: ../components/parameters/Guid.yaml - name: include in: query + required: false schema: type: array items: @@ -333,7 +373,7 @@ enum: - space - space.organization - description: Optionally include a list of unique related resources in the response + description: Optionally include additional related resources in the response; valid values are `space` and `space.organization` responses: '200': description: Successfully retrieved app @@ -345,7 +385,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app state: STOPPED created_at: '2016-03-17T21:41:30Z' @@ -359,10 +399,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -414,7 +454,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update an app - description: Update an app. + description: |- + Update an app. + + **Permitted roles:** Admin, Space Developer operationId: updateApp tags: - Apps @@ -433,7 +476,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' @@ -447,10 +490,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -512,7 +555,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete an app - description: Delete an app. + description: |- + Delete an app. + + **Permitted roles:** Admin, Space Developer operationId: deleteApp tags: - Apps @@ -520,13 +566,15 @@ - $ref: ../components/parameters/Guid.yaml responses: '202': - description: Successfully deleted app + description: Accepted headers: Location: - description: URL of the job that is deleting the app + description: URL of the [job](#jobs) that is deleting the app schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -540,7 +588,10 @@ /v3/apps/{guid}/actions/start: post: summary: Start an app - description: Start an app. + description: |- + Start an app. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: startApp tags: - Apps @@ -557,7 +608,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' @@ -571,10 +622,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -618,7 +669,10 @@ /v3/apps/{guid}/actions/stop: post: summary: Stop an app - description: Stop an app. + description: |- + Stop an app. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: stopApp tags: - Apps @@ -635,9 +689,9 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app - state: STARTED + state: STOPPED created_at: '2016-03-17T21:41:30Z' updated_at: '2016-03-18T11:32:30Z' lifecycle: @@ -649,10 +703,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -696,7 +750,15 @@ /v3/apps/{guid}/actions/restart: post: summary: Restart an app - description: This endpoint will synchronously stop and start an application. Unlike the start and stop actions, this endpoint will error if the app is not successfully stopped in the runtime. For restarting applications without downtime, see the deployments resource. + description: |- + This endpoint will synchronously stop and start an application. + Unlike the [start](#start-an-app) and [stop](#stop-an-app) actions, + this endpoint will error if the app is not successfully stopped + in the runtime. + + For restarting applications without downtime, see the [deployments](#deployments) resource. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: restartApp tags: - Apps @@ -713,7 +775,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 name: my_app state: STARTED created_at: '2016-03-17T21:41:30Z' @@ -727,10 +789,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 current_droplet: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 links: self: href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 @@ -774,7 +836,10 @@ /v3/apps/{guid}/droplets: get: summary: List droplets for an app - description: Retrieve all droplets belonging to an app. + description: |- + Retrieve a list of droplets belonging to an app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppDroplets tags: - Apps @@ -783,10 +848,21 @@ - $ref: ../components/parameters/Guid.yaml - $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` and `updated_at` - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: @@ -794,6 +870,7 @@ description: Comma-delimited list of droplet guids to filter by - name: states in: query + required: false schema: type: array items: @@ -806,6 +883,12 @@ - FAILED - EXPIRED description: Comma-delimited list of droplet states to filter by + - name: current + in: query + required: false + schema: + type: boolean + description: If true, only include the droplet currently assigned to the app responses: '200': description: List of droplets for the app @@ -821,13 +904,13 @@ total_results: 2 total_pages: 1 first: - href: https://api.example.org?page=1&per_page=50 + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50 last: - href: https://api.example.org?page=1&per_page=50 + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50 next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 state: STAGED error: null lifecycle: @@ -851,7 +934,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 @@ -867,7 +950,7 @@ metadata: labels: {} annotations: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fdf3851c-def8-4de1-87f1-6d4543189e22 state: STAGED error: null lifecycle: @@ -885,7 +968,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22 @@ -908,7 +991,10 @@ /v3/apps/{guid}/droplets/current: get: summary: Get current droplet - description: Get the current droplet for an app. + description: |- + Get the current droplet for an app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getCurrentDropletForApp tags: - Apps @@ -925,7 +1011,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 state: STAGED error: null lifecycle: @@ -950,7 +1036,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 @@ -975,7 +1061,10 @@ /v3/apps/{guid}/relationships/current_droplet: get: summary: Get current droplet association for an app - description: This endpoint retrieves the current droplet relationship for an app. + description: |- + This endpoint retrieves the current droplet relationship for an app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getCurrentDropletAssociationForApp tags: - Apps @@ -993,7 +1082,7 @@ summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 links: self: href: https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet @@ -1007,7 +1096,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Set current droplet - description: Set the current droplet for an app. The current droplet is the droplet that the app will use when running. + description: |- + Set the current droplet for an app. The current droplet is the droplet that the app will use when running. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: setCurrentDropletForApp tags: - Apps @@ -1023,6 +1115,7 @@ properties: data: $ref: ../components/schemas/Relationship.yaml + description: The guid of the droplet to set as the app's current droplet required: - data description: Request schema for setting the current droplet @@ -1031,7 +1124,7 @@ summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 responses: '200': description: Successfully set current droplet @@ -1044,7 +1137,7 @@ summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 links: self: href: https://api.example.org/v3/apps/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/current_droplet @@ -1061,7 +1154,11 @@ /v3/apps/{guid}/env: get: summary: Get environment for an app - description: Retrieve the environment variables that will be provided to an app at runtime. It will include environment variables for Environment Variable Groups and Service Bindings. + description: |- + Retrieve the environment variables that will be provided to an app at runtime. + It will include environment variables for Environment Variable Groups and Service Bindings. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer, Space Supporter *(`system_env_json` redacted)* operationId: getEnvForApp tags: - Apps @@ -1125,7 +1222,11 @@ /v3/apps/{guid}/environment_variables: get: summary: Get environment variables for an app - description: Retrieve the environment variables that are associated with the given app. For the entire list of environment variables that will be available to the app at runtime, see the env endpoint. + description: |- + Retrieve the environment variables that are associated with the given app. + For the entire list of environment variables that will be available to the app at runtime, see the [env endpoint](#get-environment-for-an-app). + + **Permitted roles:** Admin, Admin Read-Only, Space Developer, Space Supporter operationId: getEnvironmentVariablesForApp tags: - Apps @@ -1146,9 +1247,9 @@ RAILS_ENV: production links: self: - href: https://api.example.org/v3/apps/[guid]/environment_variables + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables app: - href: https://api.example.org/v3/apps/[guid] + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -1157,13 +1258,23 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update environment variables for an app - description: Update the environment variables associated with the given app. The variables given in the request will be merged with the existing app environment variables. Any requested variables with a value of `null` will be removed from the app. Environment variable names may not start with VCAP_. PORT is not a valid environment variable. The updated environment variables will not take effect until the app is restarted. + description: |- + Update the environment variables associated with the given app. + The variables given in the request will be merged with the existing app environment variables. + Any requested variables with a value of `null` will be removed from the app. + Environment variable names may not start with VCAP_. PORT is not a valid environment variable. + + > **Note:** The updated environment variables will not take effect until the app is restarted. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: updateEnvironmentVariablesForApp tags: - Apps parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: The environment variables to merge into the app's existing environment variables + required: true content: application/json: schema: @@ -1173,7 +1284,8 @@ type: object additionalProperties: type: [string, "null"] - description: Environment variables to inject; keys and values must be strings + description: Environment variables to be used for the app when running; a value of `null` removes the variable from the app + description: Request schema for updating an app's environment variables examples: default: summary: default @@ -1197,9 +1309,9 @@ DEBUG: 'false' links: self: - href: https://api.example.org/v3/apps/[guid]/environment_variables + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/environment_variables app: - href: https://api.example.org/v3/apps/[guid] + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -1211,7 +1323,12 @@ /v3/apps/{guid}/permissions: get: summary: Get permissions for an app - description: Get the current user’s permissions for the given app. If a user can see an app, then they can see its basic data. Only admin, read-only admins, and space developers can read sensitive data. + description: |- + Get the current user's permissions for the given app. If a user can see an app, + then they can see its basic data. Only admin, read-only admins, and space + developers can read sensitive data. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getPermissionsForApp tags: - Apps @@ -1239,7 +1356,13 @@ /v3/apps/{guid}/ssh_enabled: get: summary: Get SSH enabled for an app - description: Returns if an application’s runtime environment will accept ssh connections. If ssh is disabled, the `reason` field will describe whether it is disabled globally, at the space level, or at the app level. + description: |- + Returns if an application's runtime environment will accept ssh connections. + If ssh is disabled, + the `reason` field will describe + whether it is disabled globally, at the space level, or at the app level. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getSshEnabledForApp tags: - Apps @@ -1267,7 +1390,14 @@ /v3/apps/{guid}/actions/clear_buildpack_cache: post: summary: Clear buildpack cache for application - description: This endpoint will delete the buildpack cache for a specified app. The buildpack cache is used during staging by buildpacks as a way to cache certain resources, e.g. downloaded Ruby gems. A user may want to use this endpoint when an app doesn’t stage anymore due to out-of-disk caused by a large buildpack cache content. + description: |- + This endpoint will delete the buildpack cache for a specified app. + The buildpack cache is used during staging by buildpacks as a way to + cache certain resources, e.g. downloaded Ruby gems. A user may want to use this + endpoint when an app doesn't stage anymore due to out-of-disk caused + by a large buildpack cache content. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: clearBuildpackCacheForApplication tags: - Apps @@ -1276,6 +1406,14 @@ responses: '202': description: Accepted + headers: + Location: + description: URL of the [job](#jobs) that is clearing the buildpack cache + schema: + type: string + format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -1287,15 +1425,48 @@ /v3/apps/{guid}/features: get: summary: List app features - description: This endpoint retrieves the list of features for the specified app. + description: |- + This endpoint retrieves the list of features for the specified app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppFeatures tags: - - Apps + - App Features parameters: - $ref: ../components/parameters/Guid.yaml responses: '200': description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AppFeatureList.yaml + examples: + default: + summary: default + value: + resources: + - name: ssh + description: Enable SSHing into the app. + enabled: true + - name: revisions + description: Enable versioning of an application + enabled: false + - name: service-binding-k8s + description: Enable k8s service bindings for the app + enabled: false + - name: file-based-vcap-services + description: Enable file-based VCAP service bindings for the app + enabled: false + pagination: + total_results: 4 + total_pages: 1 + first: + href: /v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features + last: + href: /v3/apps/05d39de4-2c9e-4c76-8fd6-10417da07e42/features + next: null + previous: null '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -1305,10 +1476,13 @@ /v3/apps/{guid}/features/{name}: get: summary: Get an app feature - description: Get an app feature. + description: |- + Retrieve a single feature for the specified app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getAppFeature tags: - - Apps + - App Features parameters: - $ref: ../components/parameters/Guid.yaml - name: name @@ -1321,9 +1495,21 @@ - revisions - service-binding-k8s - file-based-vcap-services + description: Name of the app feature; valid values are `ssh`, `revisions`, `service-binding-k8s`, `file-based-vcap-services` responses: '200': description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AppFeature.yaml + examples: + default: + summary: default + value: + name: ssh + description: Enable SSHing into the app. + enabled: true '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -1332,10 +1518,15 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update an app feature - description: Update an app feature. + description: |- + Enable or disable a feature for the specified app. + + Only one of `file-based-vcap-services` and `service-binding-k8s` may be enabled for an app at a time. + + **Permitted roles:** Admin, Space Developer, Space Supporter *(can only update **revisions** feature)* operationId: updateAppFeature tags: - - Apps + - App Features parameters: - $ref: ../components/parameters/Guid.yaml - name: name @@ -1348,13 +1539,21 @@ - revisions - service-binding-k8s - file-based-vcap-services + description: Name of the app feature; valid values are `ssh`, `revisions`, `service-binding-k8s`, `file-based-vcap-services` requestBody: + description: The app feature state that needs to be set + required: true content: application/json: schema: + type: object properties: enabled: type: boolean + description: Denotes whether or not the app feature should be enabled + required: + - enabled + description: Request schema for updating an app feature examples: default: summary: default @@ -1363,6 +1562,17 @@ responses: '200': description: OK + content: + application/json: + schema: + $ref: ../components/schemas/AppFeature.yaml + examples: + default: + summary: default + value: + name: ssh + description: Enable SSHing into the app. + enabled: true '400': $ref: ../components/responses/BadRequest.yaml '401': diff --git a/docs/openapi/apis/cf/latest/paths/AuditEvents.yaml b/docs/openapi/apis/cf/latest/paths/AuditEvents.yaml index 09ccda7827e..b5b58660b75 100644 --- a/docs/openapi/apis/cf/latest/paths/AuditEvents.yaml +++ b/docs/openapi/apis/cf/latest/paths/AuditEvents.yaml @@ -1,18 +1,17 @@ /v3/audit_events: get: summary: List audit events - description: Retrieve all audit events the user has access to. + description: |- + Retrieve all audit events the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAuditEvents tags: - Audit Events parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - name: types in: query + required: false schema: type: array items: @@ -20,6 +19,8 @@ enum: - audit.app.apply_manifest - audit.app.build.create + - audit.app.build.failed + - audit.app.build.staged - audit.app.copy-bits - audit.app.create - audit.app.delete-request @@ -60,15 +61,26 @@ - audit.app.unmap-route - audit.app.update - audit.app.upload-bits + - audit.buildpack.create + - audit.buildpack.delete + - audit.buildpack.update + - audit.buildpack.upload - audit.organization.create - audit.organization.delete-request - audit.organization.update + - audit.organization_quota.apply + - audit.organization_quota.create + - audit.organization_quota.delete + - audit.organization_quota.update - audit.route.create - audit.route.delete-request - audit.route.share - audit.route.transfer-owner - audit.route.unshare - audit.route.update + - audit.route_policy.create + - audit.route_policy.delete + - audit.route_policy.update - audit.service.create - audit.service.delete - audit.service.update @@ -115,6 +127,14 @@ - audit.space.create - audit.space.delete-request - audit.space.update + - audit.space_quota.apply + - audit.space_quota.create + - audit.space_quota.delete + - audit.space_quota.remove + - audit.space_quota.update + - audit.stack.create + - audit.stack.delete + - audit.stack.update - audit.user.organization_auditor_add - audit.user.organization_auditor_remove - audit.user.organization_billing_manager_add @@ -140,13 +160,15 @@ description: Comma-delimited list of event types to filter by - name: target_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of target guids to filter by. Also supports filtering by exclusion. + description: Comma-delimited list of target guids to filter by. Also supports [filtering by exclusion](#exclusion-operator), for example `target_guids[not]=guid-1,guid-2` - name: space_guids in: query + required: false schema: type: array items: @@ -154,11 +176,39 @@ description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false 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 + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at` + - name: created_ats + in: query + required: false + schema: + type: string + description: Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators), for example `created_ats[gt]`, `created_ats[gte]`, `created_ats[lt]` and `created_ats[lte]` + example: '2021-01-01T00:00:00Z' + - name: updated_ats + in: query + required: false + schema: + type: string + description: Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators), for example `updated_ats[gt]`, `updated_ats[gte]`, `updated_ats[lt]` and `updated_ats[lte]` + example: '2021-01-01T00:00:00Z' responses: '200': description: OK @@ -174,9 +224,9 @@ total_results: 1 total_pages: 1 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/audit_events?page=1&per_page=2 last: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/audit_events?page=1&per_page=2 next: null previous: null resources: @@ -201,7 +251,7 @@ guid: 123e4567-e89b-12d3-a456-426614174000 links: self: - href: https://api.example.org//a595fe2f-01ff-4965-a50c-290258ab8582 + href: https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -221,12 +271,21 @@ /v3/audit_events/{guid}: get: summary: Get an audit event - description: Retrieve a specific audit event. + description: |- + Retrieve a specific audit event. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor *(cannot see events which occurred in orgs that the user does not belong to)*, Space Auditor *(cannot see events which occurred in spaces that the user does not belong to)*, Space Developer *(cannot see events which occurred in spaces that the user does not belong to)*, Space Supporter *(cannot see events which occurred in spaces that the user does not belong to)* operationId: getAuditEvent tags: - Audit Events parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the audit event responses: '200': description: OK diff --git a/docs/openapi/apis/cf/latest/paths/Buildpacks.yaml b/docs/openapi/apis/cf/latest/paths/Buildpacks.yaml index 4d49f9115c1..889ed53015c 100644 --- a/docs/openapi/apis/cf/latest/paths/Buildpacks.yaml +++ b/docs/openapi/apis/cf/latest/paths/Buildpacks.yaml @@ -1,33 +1,59 @@ /v3/buildpacks: get: summary: List buildpacks - description: Retrieve all buildpacks. + description: |- + Retrieve all buildpacks the user has access to. + + **Permitted roles:** All Roles operationId: listBuildpacks tags: - Buildpacks parameters: - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - - $ref: ../components/parameters/LabelSelector.yaml - name: names in: query + required: false schema: type: array items: type: string - description: | - Comma-delimited list of buildpack names to filter by + description: Comma-delimited list of buildpack names to filter by (case-sensitive) - name: stacks in: query + required: false schema: type: array items: type: string - description: | - Comma-delimited list of stacks to filter by + description: Comma-delimited list of stack names to filter by (case-sensitive) + - name: lifecycle + in: query + required: false + schema: + type: string + enum: + - buildpack + - cnb + description: Type of buildpack. Valid values are `buildpack` and `cnb` + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + - updated_at + - -updated_at + - lifecycle + - -lifecycle + - position + - -position + description: Value to sort by; defaults to ascending. Prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`, `lifecycle`, and `position` + - $ref: ../components/parameters/LabelSelector.yaml + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml responses: '200': description: OK @@ -50,7 +76,7 @@ href: https://api.example.org/v3/buildpacks?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 created_at: '2016-03-18T23:26:46Z' updated_at: '2016-10-17T20:00:42Z' name: my-buildpack @@ -88,7 +114,7 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a buildpack - description: Create a buildpack. + description: '**Permitted roles:** Admin' operationId: createBuildpack tags: - Buildpacks @@ -114,7 +140,7 @@ /v3/buildpacks/{guid}: get: summary: Get a buildpack - description: Retrieve a buildpack. + description: '**Permitted roles:** All Roles' operationId: getBuildpack tags: - Buildpacks @@ -133,7 +159,7 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a buildpack - description: Update a buildpack. + description: '**Permitted roles:** Admin' operationId: updateBuildpack tags: - Buildpacks @@ -148,6 +174,30 @@ application/json: schema: $ref: ../components/schemas/Buildpack.yaml + examples: + default: + summary: default + value: + guid: fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + created_at: '2016-03-18T23:26:46Z' + updated_at: '2016-10-17T20:00:42Z' + name: ruby_buildpack + state: AWAITING_UPLOAD + filename: null + stack: windows64 + position: 42 + lifecycle: buildpack + enabled: true + locked: false + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + upload: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload + method: POST '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -166,7 +216,7 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a buildpack - description: Delete a buildpack. + description: '**Permitted roles:** Admin' operationId: deleteBuildpack tags: - Buildpacks @@ -177,10 +227,12 @@ description: Accepted headers: Location: - description: URL of the job that is deleting the buildpack + description: URL of the [job](#jobs) that is deleting the buildpack schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -194,14 +246,17 @@ /v3/buildpacks/{guid}/upload: post: summary: Upload buildpack bits - description: Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form. + description: |- + Upload a zip file containing a Cloud Foundry compatible buildpack. The file must be sent as part of a multi-part form. + + **Permitted roles:** Admin operationId: uploadBuildpack tags: - Buildpacks parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: The buildpack file to be uploaded + description: The buildpack file to be uploaded, sent as part of a multi-part form required: true content: multipart/form-data: @@ -211,38 +266,49 @@ bits: type: string format: binary - resources: - type: array - items: - type: object - properties: - path: - type: string - size_in_bytes: - type: integer - checksum: - type: object - properties: - value: - type: string + description: A binary zip file containing the buildpack bits + required: + - bits + description: Request schema for uploading buildpack bits responses: - '200': - description: Successfully uploaded buildpack - content: - application/json: - schema: - $ref: ../components/schemas/Buildpack.yaml '202': - description: Upload initiated + description: Accepted headers: Location: + description: URL of the [job](#jobs) that is processing the buildpack bits schema: type: string - description: URL of the job tracking the upload + format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 content: application/json: schema: $ref: ../components/schemas/Buildpack.yaml + examples: + default: + summary: default + value: + guid: fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + created_at: '2016-03-18T23:26:46Z' + updated_at: '2016-10-17T20:00:42Z' + name: ruby_buildpack + state: AWAITING_UPLOAD + filename: null + stack: windows64 + position: 42 + lifecycle: buildpack + enabled: true + locked: false + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2 + upload: + href: https://api.example.org/v3/buildpacks/fd35633f-5c5c-4e4e-a5a9-0722c970a9d2/upload + method: POST '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/Builds.yaml b/docs/openapi/apis/cf/latest/paths/Builds.yaml index 249ba31cc29..ad73577dd7b 100644 --- a/docs/openapi/apis/cf/latest/paths/Builds.yaml +++ b/docs/openapi/apis/cf/latest/paths/Builds.yaml @@ -1,19 +1,17 @@ /v3/builds: get: summary: List builds - description: Retrieve all builds. + description: |- + Retrieve all builds the user has access to. + + **Permitted roles:** All Roles operationId: listBuilds tags: - Builds parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - - $ref: ../components/parameters/LabelSelector.yaml - name: states in: query + required: false schema: type: array items: @@ -25,18 +23,36 @@ description: Comma-delimited list of build states to filter by - name: app_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app GUIDs to filter by + description: Comma-delimited list of app guids to filter by - name: package_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of package GUIDs to filter by + description: Comma-delimited list of package 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 @@ -52,17 +68,17 @@ total_results: 1 total_pages: 1 first: - href: https://api.example.org?states=STAGING&page=1&per_page=2 + href: https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2 last: - href: https://api.example.org?states=STAGING&page=1&per_page=2 + href: https://api.example.org/v3/builds?states=STAGING&page=1&per_page=2 next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-06-08T16:41:26Z' created_by: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 3cb4e243-bed4-49d5-8739-f8b45abdec1c name: bill email: bill@example.com state: STAGING @@ -77,12 +93,12 @@ - ruby_buildpack stack: cflinuxfs4 package: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8e4da443-f255-499c-8b47-b3729b5b7432 droplet: null relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 metadata: labels: {} annotations: {} @@ -109,42 +125,12 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a build - description: Create a build. + description: '**Permitted roles:** Admin, Space Developer, Space Supporter' operationId: createBuild tags: - Builds requestBody: - description: Build object that needs to be created - required: true - content: - application/json: - schema: - type: object - properties: - package: - $ref: ../components/schemas/Relationship.yaml - lifecycle: - $ref: ../components/schemas/Lifecycle.yaml - staging_memory_in_mb: - type: integer - description: Memory in MB allocated for staging of the build - staging_disk_in_mb: - type: integer - description: Disk space in MB allocated for staging of the build - staging_log_rate_limit_bytes_per_second: - type: integer - description: Log rate limit in bytes per second allocated for staging of the build - metadata: - $ref: ../components/schemas/Metadata.yaml - required: - - package - description: Request schema for creating a build - examples: - default: - summary: default - value: - package: - guid: 123e4567-e89b-12d3-a456-426614174000 + $ref: ../components/requestBodies/BuildCreateRequestBody.yaml responses: '201': description: Successfully created build @@ -152,6 +138,43 @@ application/json: schema: $ref: ../components/schemas/Build.yaml + examples: + default: + summary: default + value: + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 + created_at: '2016-03-28T23:39:34Z' + updated_at: '2016-06-08T16:41:26Z' + created_by: + guid: 3cb4e243-bed4-49d5-8739-f8b45abdec1c + name: bill + email: bill@example.com + state: STAGING + staging_memory_in_mb: 1024 + staging_disk_in_mb: 1024 + staging_log_rate_limit_bytes_per_second: 1024 + error: null + lifecycle: + type: buildpack + data: + buildpacks: + - ruby_buildpack + stack: cflinuxfs4 + package: + guid: 8e4da443-f255-499c-8b47-b3729b5b7432 + droplet: null + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16 + app: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: app: operationId: getApp @@ -175,7 +198,7 @@ /v3/builds/{guid}: get: summary: Get a build - description: Retrieve a build. + description: '**Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter' operationId: getBuild tags: - Builds @@ -188,6 +211,46 @@ application/json: schema: $ref: ../components/schemas/Build.yaml + examples: + default: + summary: default + value: + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 + created_at: '2016-03-28T23:39:34Z' + updated_at: '2016-03-28T23:39:47Z' + created_by: + guid: 3cb4e243-bed4-49d5-8739-f8b45abdec1c + name: bill + email: bill@example.com + state: STAGED + staging_memory_in_mb: 1024 + staging_disk_in_mb: 1024 + staging_log_rate_limit_bytes_per_second: 1024 + error: null + lifecycle: + type: buildpack + data: + buildpacks: + - ruby_buildpack + stack: cflinuxfs4 + package: + guid: 8e4da443-f255-499c-8b47-b3729b5b7432 + droplet: + guid: 1e1186e7-d803-4c46-b9d6-5c81e50fe55a + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16 + app: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 + droplet: + href: https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a links: app: operationId: getApp @@ -207,13 +270,17 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a build - description: Update a build. + description: |- + **Permitted roles:** Admin, Space Developer, Build State Updater + + The `Build State Updater` role is a special component role; [read more about component roles](#component-roles). operationId: updateBuild tags: - Builds parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: Build object that needs to be updated content: application/json: schema: @@ -234,6 +301,48 @@ application/json: schema: $ref: ../components/schemas/Build.yaml + examples: + default: + summary: default + value: + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 + created_at: '2016-03-28T23:39:34Z' + updated_at: '2016-03-28T23:39:47Z' + created_by: + guid: 3cb4e243-bed4-49d5-8739-f8b45abdec1c + name: bill + email: bill@example.com + state: STAGED + staging_memory_in_mb: 1024 + staging_disk_in_mb: 1024 + staging_log_rate_limit_bytes_per_second: 1024 + error: null + lifecycle: + type: buildpack + data: + buildpacks: + - ruby_buildpack + stack: cflinuxfs4 + package: + guid: 8e4da443-f255-499c-8b47-b3729b5b7432 + droplet: + guid: 1e1186e7-d803-4c46-b9d6-5c81e50fe55a + relationships: + app: + data: + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 + metadata: + labels: + key: value + annotations: + note: detailed information + links: + self: + href: https://api.example.org/v3/builds/585bc3c1-3743-497d-88b0-403ad6b56d16 + app: + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 + droplet: + href: https://api.example.org/v3/droplets/1e1186e7-d803-4c46-b9d6-5c81e50fe55a '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -253,17 +362,19 @@ /v3/apps/{guid}/builds: get: summary: List builds for an app - description: Retrieve all builds for an app. + description: |- + Retrieve all builds for the app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppBuilds tags: - Builds parameters: - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml + description: The guid of the app - name: states in: query + required: false schema: type: array items: @@ -273,6 +384,19 @@ - STAGED - FAILED description: Comma-delimited list of build states 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 @@ -291,17 +415,17 @@ total_results: 1 total_pages: 1 first: - href: https://api.example.org?states=STAGING&page=1&per_page=2 + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/builds?states=STAGING&page=1&per_page=2 last: - href: https://api.example.org?states=STAGING&page=1&per_page=2 + href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/builds?states=STAGING&page=1&per_page=2 next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 created_at: '2016-03-28T23:39:34Z' updated_at: '2016-06-08T16:41:26Z' created_by: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 3cb4e243-bed4-49d5-8739-f8b45abdec1c name: bill email: bill@example.com state: STAGING @@ -316,12 +440,12 @@ - ruby_buildpack stack: cflinuxfs4 package: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8e4da443-f255-499c-8b47-b3729b5b7432 droplet: null relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 metadata: labels: {} annotations: {} @@ -336,37 +460,3 @@ $ref: ../components/responses/Forbidden.yaml '404': $ref: ../components/responses/NotFound.yaml - patch: - summary: Update a build - description: Update a build. - operationId: updateBuildViaApp - tags: - - Builds - parameters: - - $ref: ../components/parameters/Guid.yaml - requestBody: - description: Build 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 build - responses: - '200': - description: Successfully updated build - content: - application/json: - schema: - $ref: ../components/schemas/Build.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 diff --git a/docs/openapi/apis/cf/latest/paths/Deployments.yaml b/docs/openapi/apis/cf/latest/paths/Deployments.yaml index c79e34ae9c6..e2d11032fc7 100644 --- a/docs/openapi/apis/cf/latest/paths/Deployments.yaml +++ b/docs/openapi/apis/cf/latest/paths/Deployments.yaml @@ -1,26 +1,41 @@ /v3/deployments: get: summary: List deployments - description: Retrieve all deployments. + description: |- + Retrieve all deployments the user has access to. + + **Permitted roles:** All Roles operationId: listDeployments tags: - Deployments 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 - name: app_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app GUIDs to filter by + description: Comma-delimited list of app guids to filter by - name: states in: query + required: false schema: type: array items: @@ -28,6 +43,7 @@ description: Comma-delimited list of states to filter by - name: status_reasons in: query + required: false schema: type: array items: @@ -39,9 +55,10 @@ - DEPLOYED - CANCELED - SUPERSEDED - description: Comma-delimited list of status reasons to filter by + description: Comma-delimited list of status reasons to filter by; valid values include `DEPLOYING`, `PAUSED`, `CANCELING`, `DEPLOYED`, `CANCELED`, `SUPERSEDED` - name: status_values in: query + required: false schema: type: array items: @@ -49,7 +66,7 @@ enum: - ACTIVE - FINALIZED - description: Comma-delimited list of status values to filter by + description: Comma-delimited list of status values to filter by; valid values include `ACTIVE` and `FINALIZED` responses: '200': description: OK @@ -123,7 +140,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a deployment - description: When you create a new deployment you can either provide a specific droplet or revision to deploy. If no revision or droplet is provided, the droplet associated with the app is deployed. + description: |- + When you create a new deployment you can either provide a specific droplet or revision to deploy. If no revision or droplet is provided, the droplet associated with the [app](#apps) is deployed. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: createDeployment tags: - Deployments @@ -134,54 +154,89 @@ application/json: schema: type: object + required: + - relationships properties: relationships: - $ref: ../components/schemas/Relationships.yaml + type: object + description: Relationships to other resources + required: + - app + properties: + app: + $ref: ../components/schemas/RelationshipToOne.yaml + description: The app to deploy a droplet for + droplet: + $ref: ../components/schemas/Relationship.yaml + description: The droplet to deploy for the app; this will update the app's [current droplet](#get-current-droplet-association-for-an-app) to this droplet. Defaults to the app's [current droplet](#get-current-droplet-association-for-an-app). Only a droplet *or* a revision may be provided, not both. + revision: + $ref: ../components/schemas/Relationship.yaml + description: The [revision](#revisions) whose droplet to deploy for the app; this will update the app's [current droplet](#get-current-droplet-association-for-an-app) to this droplet. Only a droplet *or* a revision may be provided, not both. strategy: type: string + description: The strategy to use for the deployment; supported strategies are `rolling` and `canary` (experimental) + default: rolling enum: - rolling - canary options: type: object + description: Options to use for the deployment properties: max_in_flight: type: integer - description: The maximum number of instances that will be deployed simultaneously + description: The maximum number of new instances to deploy simultaneously default: 1 minimum: 1 web_instances: type: integer - description: The number of instances for the web process of the new droplet + description: The number of web instances the deployment will scale to. Defaults to the current web process's instance count memory_in_mb: - type: integer - description: The amount of memory in megabytes to allocate for the web process + type: [integer, "null"] + description: The amount of memory in megabytes to allocate per web process instance. If `null`, the amount allocated will be taken from the previous web process. + default: null disk_in_mb: - type: integer - description: The amount of disk space in megabytes to allocate for the web process + type: [integer, "null"] + description: The amount of disk in megabytes to allocate per web process instance. If `null`, the amount allocated will be taken from the previous web process. + default: null 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. + type: [integer, "null"] + description: Log rate limit in bytes per second to allocate per web process instance. If `null`, the amount allocated will be taken from the previous web process. + default: null canary: type: object - description: Canary steps to use for the deployment. Only available for deployments with strategy ‘canary’. + description: Canary options to use for the deployment. Only valid for deployments with strategy `canary`. (experimental) properties: steps: type: array - description: Array of steps defining the canary deployment progression + description: An array of canary steps to use for the deployment. (experimental) items: type: object + description: A canary step 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: - $ref: ../components/schemas/Relationship.yaml + description: The percentage of instances to be deployed as part of the canary process in this step (experimental) + minimum: 1 + maximum: 100 metadata: $ref: ../components/schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the deployment + + `annotations`: Annotations applied to the deployment + description: Request schema for creating a deployment examples: + droplet: + summary: Create a deployment with a droplet + value: + droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + strategy: rolling + relationships: + app: + data: + guid: 123e4567-e89b-12d3-a456-426614174000 default: summary: default value: @@ -199,6 +254,62 @@ application/json: schema: $ref: ../components/schemas/Deployment.yaml + examples: + default: + summary: default + value: + guid: 123e4567-e89b-12d3-a456-426614174000 + status: + value: ACTIVE + reason: DEPLOYING + details: + last_successful_healthcheck: '2018-04-25T22:42:10Z' + last_status_change: '2018-04-25T22:42:10Z' + canary: + steps: + current: 1 + total: 2 + strategy: canary + options: + max_in_flight: 3 + web_instances: 5 + memory_in_mb: 1024 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: -1 + canary: + steps: + - instance_weight: 10 + - instance_weight: 20 + droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + previous_droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + new_processes: + - guid: 123e4567-e89b-12d3-a456-426614174000 + type: web + revision: + guid: 123e4567-e89b-12d3-a456-426614174000 + version: 1 + created_at: '2018-04-25T22:42:10Z' + updated_at: '2018-04-25T22:42:10Z' + metadata: + labels: {} + annotations: {} + relationships: + app: + data: + guid: 123e4567-e89b-12d3-a456-426614174000 + links: + self: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4 + app: + href: https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2 + cancel: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel + method: POST + continue: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue + method: POST links: app: operationId: getApp @@ -232,12 +343,16 @@ /v3/deployments/{guid}: get: summary: Get a deployment - description: Retrieve a deployment. + description: |- + Retrieve a deployment. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getDeployment tags: - Deployments parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the deployment responses: '200': description: Successfully retrieved deployment @@ -245,6 +360,62 @@ application/json: schema: $ref: ../components/schemas/Deployment.yaml + examples: + default: + summary: default + value: + guid: 123e4567-e89b-12d3-a456-426614174000 + status: + value: ACTIVE + reason: DEPLOYING + details: + last_successful_healthcheck: '2018-04-25T22:42:10Z' + last_status_change: '2018-04-25T22:42:10Z' + canary: + steps: + current: 1 + total: 2 + strategy: canary + options: + max_in_flight: 3 + web_instances: 5 + memory_in_mb: 1024 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: -1 + canary: + steps: + - instance_weight: 10 + - instance_weight: 20 + droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + previous_droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + new_processes: + - guid: 123e4567-e89b-12d3-a456-426614174000 + type: web + revision: + guid: 123e4567-e89b-12d3-a456-426614174000 + version: 1 + created_at: '2018-04-25T22:42:10Z' + updated_at: '2018-04-25T22:42:10Z' + metadata: + labels: {} + annotations: {} + relationships: + app: + data: + guid: 123e4567-e89b-12d3-a456-426614174000 + links: + self: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4 + app: + href: https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2 + cancel: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel + method: POST + continue: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue + method: POST links: app: operationId: getApp @@ -269,12 +440,16 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a deployment - description: Update a deployment. + description: |- + Update a deployment. + + **Permitted roles:** Admin, Space Developer operationId: updateDeployment tags: - Deployments parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the deployment requestBody: description: Deployment object that needs to be updated required: true @@ -285,6 +460,10 @@ properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the deployment + + `annotations`: Annotations applied to the deployment description: Request schema for updating a deployment examples: default: @@ -302,6 +481,64 @@ application/json: schema: $ref: ../components/schemas/Deployment.yaml + examples: + default: + summary: default + value: + guid: 123e4567-e89b-12d3-a456-426614174000 + status: + value: ACTIVE + reason: DEPLOYING + details: + last_successful_healthcheck: '2018-04-25T22:42:10Z' + last_status_change: '2018-04-25T22:42:10Z' + canary: + steps: + current: 1 + total: 2 + strategy: canary + options: + max_in_flight: 3 + web_instances: 5 + memory_in_mb: 1024 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: -1 + canary: + steps: + - instance_weight: 10 + - instance_weight: 20 + droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + previous_droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + new_processes: + - guid: 123e4567-e89b-12d3-a456-426614174000 + type: web + revision: + guid: 123e4567-e89b-12d3-a456-426614174000 + version: 1 + created_at: '2018-04-25T22:42:10Z' + updated_at: '2018-04-25T22:42:10Z' + metadata: + labels: + key: value + annotations: + note: detailed information + relationships: + app: + data: + guid: 123e4567-e89b-12d3-a456-426614174000 + links: + self: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4 + app: + href: https://api.example.org/v3/apps/305cea31-5a44-45ca-b51b-e89c7a8ef8b2 + cancel: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/cancel + method: POST + continue: + href: https://api.example.org/v3/deployments/59c3d133-2b83-46f3-960e-7765a129aea4/actions/continue + method: POST '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -321,19 +558,25 @@ /v3/deployments/{guid}/actions/cancel: post: summary: Cancel a deployment - description: Cancel a deployment. + description: |- + Cancel a deployment. + + Canceling reverts the application to the state it was in before the deployment started. This involves scaling up the original web process, removing any deployment artifacts, and resetting the current droplet on the application. + + Only a deployment whose **status.value** is `ACTIVE` can be canceled; canceling any other deployment is rejected with a `422 Unprocessable Entity`. + + > **Warning:** There is no guarantee about zero-downtime during a cancel. The goal is to revert to the original state as quickly as possible. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: cancelDeployment tags: - Deployments parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the deployment responses: '200': - description: Successfully canceled deployment - content: - application/json: - schema: - $ref: ../components/schemas/Deployment.yaml + description: Successfully canceled deployment; the response has an empty body '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -345,19 +588,23 @@ /v3/deployments/{guid}/actions/continue: post: summary: Continue a deployment - description: Continue a deployment. + description: |- + Continue a deployment. + + [Canary deployments](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html#canary-deployment-process) deploy a single instance and pause for user evaluation. If the canary instance is deemed successful, the deployment can be resumed via this action. The deployment then continues like a rolling deployment. This feature is experimental and is subject to change. + + Only a paused deployment (**status.value** `ACTIVE` and **status.reason** `PAUSED`) can be continued; continuing any other deployment is rejected with a `422 Unprocessable Entity`. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: continueDeployment tags: - Deployments parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the deployment responses: '200': - description: Successfully continued deployment - content: - application/json: - schema: - $ref: ../components/schemas/Deployment.yaml + description: Successfully continued deployment; the response has an empty body '401': $ref: ../components/responses/Unauthorized.yaml '403': 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/Droplets.yaml b/docs/openapi/apis/cf/latest/paths/Droplets.yaml index 301f900457c..f59a5e4447b 100644 --- a/docs/openapi/apis/cf/latest/paths/Droplets.yaml +++ b/docs/openapi/apis/cf/latest/paths/Droplets.yaml @@ -1,27 +1,41 @@ /v3/droplets: get: summary: List droplets - description: Retrieve all droplets. + description: |- + Retrieve all droplets the user has access to. + + **Permitted roles:** All Roles operationId: listDroplets tags: - Droplets 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` and `updated_at` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: type: string - description: | - Comma-delimited list of droplet GUIDs to filter by + description: Comma-delimited list of droplet guids to filter by - name: states in: query + required: false schema: type: array items: @@ -33,38 +47,37 @@ - COPYING - FAILED - EXPIRED - description: | - Comma-delimited list of droplet states to filter by + description: Comma-delimited list of droplet states to filter by - name: app_guids in: query + required: false schema: type: array items: type: string - description: | - Comma-delimited list of app GUIDs to filter by + description: Comma-delimited list of app guids to filter by - name: current in: query + required: false schema: type: boolean - description: | - If true, only include the current droplet for each app + description: If true, only include the current droplet for each app - name: space_guids in: query + required: false schema: type: array items: type: string - description: | - Comma-delimited list of space GUIDs to filter by + description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false 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 @@ -80,13 +93,13 @@ total_results: 2 total_pages: 1 first: - href: https://api.example.org?page=1&per_page=50 + href: https://api.example.org/v3/droplets?page=1&per_page=50 last: - href: https://api.example.org?page=1&per_page=50 + href: https://api.example.org/v3/droplets?page=1&per_page=50 next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 state: STAGED error: null lifecycle: @@ -95,7 +108,7 @@ image: null execution_metadata: PRIVATE DATA HIDDEN process_types: - redacted_message: 123e4567-e89b-12d3-a456-426614174000 + redacted_message: '[PRIVATE DATA HIDDEN IN LISTS]' checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 @@ -110,7 +123,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 @@ -126,15 +139,15 @@ metadata: labels: {} annotations: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fdf3851c-def8-4de1-87f1-6d4543189e22 state: STAGED error: null lifecycle: type: docker data: {} - execution_metadata: 123e4567-e89b-12d3-a456-426614174000 + execution_metadata: '[PRIVATE DATA HIDDEN IN LISTS]' process_types: - redacted_message: 123e4567-e89b-12d3-a456-426614174000 + redacted_message: '[PRIVATE DATA HIDDEN IN LISTS]' image: cloudfoundry/diego-docker-app-custom:latest checksum: null buildpacks: null @@ -144,7 +157,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22 @@ -175,70 +188,29 @@ '503': $ref: ../components/responses/ServiceUnavailable.yaml post: - summary: Create a droplet - description: This endpoint is only for creating a droplet without a package. To create a droplet based on a package, see [Create a build](#create-a-build). + summary: Create or copy a droplet + description: |- + This endpoint is only for creating a droplet without a package. To create a droplet based on a package, see [Create a build](#create-a-build). + + **Copy a droplet:** supplying the optional `source_guid` query parameter copies the droplet identified by `source_guid` to a different app instead of creating a new droplet. The copied droplet excludes the environment variables listed on the source droplet. In copy mode the only accepted body parameter is `relationships.app`, a relationship to the destination app; `process_types` is not accepted. + + **Permitted roles:** Admin, Space Developer operationId: createDroplet tags: - Droplets + parameters: + - name: source_guid + in: query + required: false + schema: + type: string + format: uuid + description: Source guid of the droplet to be copied. When supplied, the droplet is copied to the app given in `relationships.app` rather than created from scratch requestBody: $ref: ../components/requestBodies/DropletCreateRequestBody.yaml responses: '201': - description: Droplet created - content: - application/json: - schema: - $ref: ../components/schemas/Droplet.yaml - examples: - default: - summary: default - value: - guid: 123e4567-e89b-12d3-a456-426614174000 - state: AWAITING_UPLOAD - error: null - lifecycle: - type: buildpack - data: {} - execution_metadata: '' - process_types: - rake: bundle exec rake - web: bundle exec rackup config.ru -p $PORT - checksum: - type: sha256 - value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 - buildpacks: - - name: ruby_buildpack - detect_output: ruby 1.6.14 - version: 1.1.1. - buildpack_name: ruby - stack: cflinuxfs4 - image: null - created_at: '2016-03-28T23:39:34Z' - updated_at: '2016-03-28T23:39:47Z' - relationships: - app: - data: - guid: 123e4567-e89b-12d3-a456-426614174000 - links: - self: - href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 - app: - href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396 - assign_current_droplet: - href: https://api.example.org/v3/apps/7b34f1cf-7e73-428a-bb5a-8a17a8058396/relationships/current_droplet - method: PATCH - upload: - href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/upload - method: POST - metadata: - labels: {} - annotations: {} - links: - app: - operationId: getApp - parameters: - guid: $response.body#/relationships/app/data/guid - description: Retrieve the app for this droplet + $ref: ../components/responses/DropletCreateResponse.yaml '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -258,7 +230,10 @@ /v3/droplets/{guid}: get: summary: Get a droplet - description: Retrieve a droplet. + description: |- + Retrieve a droplet. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(some fields are redacted)*, Org Manager *(some fields are redacted)*, Space Auditor *(some fields are redacted)*, Space Developer, Space Manager *(some fields are redacted)*, Space Supporter *(some fields are redacted)* operationId: getDroplet tags: - Droplets @@ -266,7 +241,31 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: Droplet retrieved + $ref: ../components/responses/DropletGetResponse.yaml + '400': + $ref: ../components/responses/BadRequest.yaml + '401': + $ref: ../components/responses/Unauthorized.yaml + '403': + $ref: ../components/responses/Forbidden.yaml + '404': + $ref: ../components/responses/NotFound.yaml + patch: + summary: Update a droplet + description: |- + Update a droplet. + + **Permitted roles:** Admin, Space Developer, Build State Updater *(this is a special component role; [read more about component roles](#component-roles))* + operationId: updateDroplet + tags: + - Droplets + parameters: + - $ref: ../components/parameters/Guid.yaml + requestBody: + $ref: ../components/requestBodies/DropletUpdateRequestBody.yaml + responses: + '200': + description: Successfully updated droplet content: application/json: schema: @@ -275,7 +274,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 state: STAGED error: null lifecycle: @@ -300,7 +299,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 @@ -314,55 +313,10 @@ download: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16/download metadata: - labels: {} - annotations: {} - links: - app: - operationId: getApp - parameters: - guid: $response.body#/relationships/app/data/guid - description: Retrieve the app for this droplet - '400': - $ref: ../components/responses/BadRequest.yaml - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml - patch: - summary: Update a droplet - description: Update a droplet. - operationId: updateDroplet - tags: - - Droplets - parameters: - - $ref: ../components/parameters/Guid.yaml - requestBody: - description: Droplet object that needs to be updated - required: true - content: - application/json: - schema: - type: object - properties: - metadata: - $ref: ../components/schemas/Metadata.yaml - image: - type: string - description: Image reference where the built complete image was stored - required: [] - description: Request schema for updating a droplet - examples: - default: - summary: default - value: - metadata: - labels: - key: value - annotations: - note: detailed information - responses: - '200': - $ref: ../components/responses/DropletGetResponse.yaml + labels: + release: stable + annotations: + note: detailed information '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -374,18 +328,17 @@ '409': $ref: ../components/responses/Conflict.yaml '422': - description: Unprocessable Entity - content: - application/json: - schema: - $ref: ../components/schemas/Error.yaml + $ref: ../components/responses/UnprocessableEntity.yaml '500': $ref: ../components/responses/500.yaml '503': $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a droplet - description: Delete a droplet. + description: |- + Delete a droplet. + + **Permitted roles:** Admin, Space Developer operationId: deleteDroplet tags: - Droplets @@ -400,10 +353,6 @@ schema: type: string format: uri - content: - application/json: - schema: - $ref: ../components/schemas/Job.yaml '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -418,9 +367,11 @@ get: summary: Download droplet bits description: |- - Download a gzip compressed tarball file containing a Cloud Foundry compatible droplet. - When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be relayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token. + Download a gzip compressed tarball file containing a Cloud Foundry compatible droplet. When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be relayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token. + Only droplets that are in the `STAGED` state and have lifecycle type `buildpack` can be downloaded. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager operationId: downloadDroplet tags: - Droplets @@ -428,17 +379,21 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: The droplet bits; returned directly when the blobstore is local to the Cloud Controller content: application/octet-stream: schema: type: string format: binary - text/html: + description: A gzip compressed tarball containing the droplet + '302': + description: Redirect to the actual location of the bits in the remote blobstore + headers: + Location: + description: URL of the droplet bits in the blobstore schema: type: string - '302': - description: Redirect to download location + format: uri '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -452,69 +407,65 @@ /v3/droplets/{guid}/upload: post: summary: Upload droplet bits - description: Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form. + description: |- + Upload a gzip compressed tarball file containing a Cloud Foundry compatible droplet. The file must be sent as part of a multi-part form. + + **Permitted roles:** Admin, Space Developer operationId: uploadDroplet tags: - Droplets parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: The droplet file to be uploaded - required: true - content: - multipart/form-data: - schema: - type: object - properties: - bits: - type: string - format: binary - resources: - type: array - items: - type: object - properties: - path: - type: string - size_in_bytes: - type: integer - checksum: - type: object - properties: - value: - type: string - application/json: - schema: - type: object - properties: - resources: - type: array - items: - type: object - properties: - path: - type: string - size_in_bytes: - type: integer - checksum: - type: object - properties: - value: - type: string + $ref: ../components/requestBodies/DropletUploadRequestBody.yaml responses: - '200': - $ref: ../components/responses/DropletGetResponse.yaml '202': - description: Upload initiated + description: Upload accepted; the droplet bits are processed asynchronously headers: Location: + description: URL of the job that is processing the droplet upload schema: type: string - description: URL of the job tracking the upload + format: uri content: application/json: schema: $ref: ../components/schemas/Droplet.yaml + examples: + default: + summary: default + value: + guid: 3c64aba2-2d9e-4eea-9e07-6fec1636315e + state: PROCESSING_UPLOAD + error: null + lifecycle: + type: buildpack + data: {} + checksum: null + buildpacks: [] + stack: null + image: null + execution_metadata: '' + process_types: + rake: bundle exec rake + web: bundle exec rackup config.ru -p $PORT + created_at: '2019-05-15T22:43:54Z' + updated_at: '2019-05-15T22:53:02Z' + relationships: + app: + data: + guid: a7c7b09d-350d-4816-bf0b-18612fb2eab4 + links: + self: + href: https://api.example.org/v3/droplets/3c64aba2-2d9e-4eea-9e07-6fec1636315e + app: + href: https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4 + assign_current_droplet: + href: https://api.example.org/v3/apps/a7c7b09d-350d-4816-bf0b-18612fb2eab4/relationships/current_droplet + method: PATCH + metadata: + labels: {} + annotations: {} '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/EnvironmentVariableGroups.yaml b/docs/openapi/apis/cf/latest/paths/EnvironmentVariableGroups.yaml index f3e7c26aa21..f84c963e6d8 100644 --- a/docs/openapi/apis/cf/latest/paths/EnvironmentVariableGroups.yaml +++ b/docs/openapi/apis/cf/latest/paths/EnvironmentVariableGroups.yaml @@ -1,7 +1,10 @@ /v3/environment_variable_groups/{name}: get: summary: Get an environment variable group - description: Retrieve an environment variable group. + description: |- + Retrieve an environment variable group. + + **Permitted roles:** All Roles operationId: getEnvironmentVariableGroup tags: - Environment Variable Groups @@ -14,6 +17,7 @@ enum: - running - staging + description: The name of the group; can only be `running` or `staging` responses: '200': description: OK @@ -32,30 +36,27 @@ links: self: href: https://api.example.org/v3/environment_variable_groups/running - '400': - $ref: ../components/responses/BadRequest.yaml '401': $ref: ../components/responses/Unauthorized.yaml '403': $ref: ../components/responses/Forbidden.yaml '404': $ref: ../components/responses/NotFound.yaml - '409': - $ref: ../components/responses/Conflict.yaml - '422': - $ref: ../components/responses/UnprocessableEntity.yaml '500': $ref: ../components/responses/500.yaml - '502': - $ref: ../components/responses/BadGateway.yaml '503': $ref: ../components/responses/ServiceUnavailable.yaml patch: summary: Update environment variable group description: |- - 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. + 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. + + > **Note:** Variables updated in the **running** environment variable group will not take effect until apps are restarted. - Variables updated in the **running** environment variable group will not take effect until apps are restarted. + **Permitted roles:** Admin operationId: updateEnvironmentVariableGroup tags: - Environment Variable Groups @@ -68,6 +69,7 @@ enum: - running - staging + description: The name of the group; can only be `running` or `staging` requestBody: description: The environment variables to update required: true @@ -79,8 +81,15 @@ var: type: object additionalProperties: - type: string - description: Environment variables to inject; keys and values must be strings + type: [string, "null"] + description: Environment variables to inject; keys and values must be strings. A value of `null` removes the variable from the group + examples: + default: + summary: default + value: + var: + DEBUG: 'false' + USER: null responses: '200': description: OK @@ -92,12 +101,14 @@ default: summary: default value: + updated_at: '2016-05-04T17:00:41Z' + name: running var: RAILS_ENV: production DEBUG: 'false' links: self: - href: https://api.example.org/v3/environment_variable_groups/[name] + href: https://api.example.org/v3/environment_variable_groups/running '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -106,8 +117,6 @@ $ref: ../components/responses/Forbidden.yaml '404': $ref: ../components/responses/NotFound.yaml - '409': - $ref: ../components/responses/Conflict.yaml '422': $ref: ../components/responses/UnprocessableEntity.yaml '500': diff --git a/docs/openapi/apis/cf/latest/paths/FeatureFlags.yaml b/docs/openapi/apis/cf/latest/paths/FeatureFlags.yaml index 0e2c5af658f..68da5495750 100644 --- a/docs/openapi/apis/cf/latest/paths/FeatureFlags.yaml +++ b/docs/openapi/apis/cf/latest/paths/FeatureFlags.yaml @@ -1,21 +1,26 @@ /v3/feature_flags: get: summary: List feature flags - description: Retrieve all feature_flags. + description: |- + Retrieve all feature_flags. + + **Permitted roles:** All Roles operationId: listFeatureFlags tags: - Feature Flags parameters: - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - name: updated_ats + - name: order_by in: query required: false schema: type: string - description: | - Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. + enum: + - name + - '-name' + description: Value to sort by. Defaults to `name` ascending; prepend with `-` to sort descending. Valid value is `name` + - $ref: ../components/parameters/UpdatedAts.yaml responses: '200': description: OK @@ -58,20 +63,17 @@ $ref: ../components/responses/Unauthorized.yaml '403': $ref: ../components/responses/Forbidden.yaml - '409': - $ref: ../components/responses/Conflict.yaml - '422': - $ref: ../components/responses/UnprocessableEntity.yaml '500': $ref: ../components/responses/500.yaml - '502': - $ref: ../components/responses/BadGateway.yaml '503': $ref: ../components/responses/ServiceUnavailable.yaml /v3/feature_flags/{name}: get: summary: Get a feature flag - description: Get a feature flag. + description: |- + Get a feature flag. + + **Permitted roles:** All Roles operationId: getFeatureFlag tags: - Feature Flags @@ -87,6 +89,7 @@ - diego_docker - diego_cnb - env_var_visibility + - hash_based_routing - hide_marketplace_from_unauthenticated_users - private_domain_creation - resource_matching @@ -100,7 +103,7 @@ - task_creation - unset_roles_by_username - user_org_creation - description: The name of the feature flag + description: The name of the feature flag; must be one of the names in the [list of feature flags](#list-of-feature-flags) responses: '200': description: Successfully retrieved feature flag @@ -127,7 +130,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a feature flag - description: Update a feature flag. + description: |- + Update a feature flag. + + **Permitted roles:** Admin operationId: updateFeatureFlag tags: - Feature Flags @@ -143,6 +149,7 @@ - diego_docker - diego_cnb - env_var_visibility + - hash_based_routing - hide_marketplace_from_unauthenticated_users - private_domain_creation - resource_matching @@ -156,7 +163,7 @@ - task_creation - unset_roles_by_username - user_org_creation - description: The name of the feature flag + description: The name of the feature flag; must be one of the names in the [list of feature flags](#list-of-feature-flags) requestBody: description: Feature flag object that needs to be updated required: true @@ -169,7 +176,7 @@ type: boolean description: Whether the feature flag is enabled custom_error_message: - type: string + type: [string, "null"] description: The error string returned by the API when a client performs an action disabled by the feature flag examples: default: @@ -203,8 +210,6 @@ $ref: ../components/responses/Forbidden.yaml '404': $ref: ../components/responses/NotFound.yaml - '409': - $ref: ../components/responses/Conflict.yaml '422': $ref: ../components/responses/UnprocessableEntity.yaml '500': diff --git a/docs/openapi/apis/cf/latest/paths/Info.yaml b/docs/openapi/apis/cf/latest/paths/Info.yaml index 328a7c3fc6f..3572e21fa5e 100644 --- a/docs/openapi/apis/cf/latest/paths/Info.yaml +++ b/docs/openapi/apis/cf/latest/paths/Info.yaml @@ -1,7 +1,10 @@ /v3/info: get: summary: Get platform info - description: Get information about the platform. + description: |- + Get information about the platform. + + **Authentication:** No authentication required. operationId: getPlatformInfo tags: - Info @@ -11,50 +14,32 @@ content: application/json: schema: - type: object - properties: - name: - type: string - description: Name of the platform - build: - type: string - description: Build number of the platform - version: - type: integer - description: Version number of the platform - description: - type: string - description: Description of the platform - cli_version: - type: object - description: Minimum and recommended CLI versions - properties: - minimum: - type: string - description: Minimum CLI version - recommended: - type: string - description: Recommended CLI version - custom: - type: object - description: Custom information about the platform - additionalProperties: - type: string - links: - type: object - description: Links to related resources - properties: - self: - allOf: - - $ref: ../components/schemas/Link.yaml - - description: Link to the current endpoint - support: - allOf: - - $ref: ../components/schemas/Link.yaml - - description: Link to the support website for the platform + $ref: ../components/schemas/Info.yaml examples: default: - summary: default + summary: Response with configured values + value: + build: afa73e3fe + cli_version: + minimum: 6.22.0 + recommended: latest + custom: + arbitrary: stuff + description: Put your apps here! + name: Cloud Foundry + version: 123 + osbapi_version: '2.15' + rate_limits: + enabled: true + general_limit: 2000 + reset_interval_in_minutes: 30 + links: + self: + href: http://api.example.com/v3/info + support: + href: http://support.example.com + unconfigured: + summary: Response with unconfigured values value: build: '' cli_version: @@ -74,26 +59,19 @@ href: http://api.example.com/v3/info support: href: '' - '400': - $ref: ../components/responses/BadRequest.yaml - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml - '409': - $ref: ../components/responses/Conflict.yaml - '422': - $ref: ../components/responses/UnprocessableEntity.yaml + '429': + $ref: ../components/responses/TooManyRequests.yaml '500': $ref: ../components/responses/500.yaml - '502': - $ref: ../components/responses/BadGateway.yaml '503': $ref: ../components/responses/ServiceUnavailable.yaml /v3/info/usage_summary: get: summary: Get platform usage summary - description: This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation. + description: |- + This endpoint retrieves a high-level summary of usage across the entire Cloud Foundry installation. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor operationId: getPlatformUsageSummary tags: - Info @@ -103,44 +81,7 @@ content: application/json: schema: - type: object - properties: - usage_summary: - type: object - description: Usage summary - properties: - started_instances: - type: integer - description: Total number of process instances in the STARTED state - memory_in_mb: - type: integer - description: Sum of memory usage of all tasks in the RUNNING state and all process instances in the STARTED state - routes: - type: integer - description: Total number of routes - service_instances: - type: integer - description: Total number of managed service instances - reserved_ports: - type: integer - description: Total number of reserved ports - domains: - type: integer - description: Total number of private domains - per_app_tasks: - type: integer - description: Total number of running tasks - service_keys: - type: integer - description: Total number of service keys - links: - type: object - description: Links to related resources - properties: - self: - allOf: - - $ref: ../components/schemas/Link.yaml - - description: Link to the current endpoint + $ref: ../components/schemas/InfoUsageSummary.yaml examples: default: summary: default 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 diff --git a/docs/openapi/apis/cf/latest/paths/Jobs.yaml b/docs/openapi/apis/cf/latest/paths/Jobs.yaml index 9513037ef4e..e93fd435b83 100644 --- a/docs/openapi/apis/cf/latest/paths/Jobs.yaml +++ b/docs/openapi/apis/cf/latest/paths/Jobs.yaml @@ -1,7 +1,10 @@ /v3/jobs/{guid}: get: summary: Get a job - description: Retrieve a specific job. + description: |- + Retrieve a specific job. + + **Permitted roles:** All Roles operationId: getJob tags: - Jobs @@ -16,9 +19,22 @@ $ref: ../components/schemas/Job.yaml examples: default: - summary: default + summary: Completed job value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b19ae525-cbd3-4155-b156-dc0c2a431b4c + created_at: '2016-10-19T20:25:04Z' + updated_at: '2016-11-08T16:41:26Z' + operation: app.delete + state: COMPLETE + links: + self: + href: https://api.example.org/v3/jobs/b19ae525-cbd3-4155-b156-dc0c2a431b4c + errors: [] + warnings: [] + failed: + summary: Failed job + value: + guid: b19ae525-cbd3-4155-b156-dc0c2a431b4c created_at: '2016-10-19T20:25:04Z' updated_at: '2016-11-08T16:41:26Z' operation: app.delete diff --git a/docs/openapi/apis/cf/latest/paths/Manifests.yaml b/docs/openapi/apis/cf/latest/paths/Manifests.yaml index bb82a736c34..ba1dd000ae0 100644 --- a/docs/openapi/apis/cf/latest/paths/Manifests.yaml +++ b/docs/openapi/apis/cf/latest/paths/Manifests.yaml @@ -1,147 +1,77 @@ -/v3/spaces/{guid}/actions/apply_manifest: - post: - summary: Apply a manifest to a space - description: 'Apply changes specified in a manifest to the named apps and their - underlying processes. The apps must reside in the space. These changes are additive - and will not modify any unspecified properties or remove any existing environment - variables, app features, routes, or services. - - - Apply manifest will only trigger an immediate update for the “instances” property - or routing changes. All other properties require an app restart to take effect.' - operationId: applyManifest - tags: - - Manifests - parameters: - - $ref: '../components/parameters/Guid.yaml' - requestBody: - content: - application/x-yaml: - schema: - type: string - responses: - '202': - description: Accepted - headers: - Location: - description: URL of the job that is applying the manifest - schema: - type: string - format: uri - '401': - $ref: '../components/responses/Unauthorized.yaml' - '404': - $ref: '../components/responses/NotFound.yaml' - '403': - $ref: '../components/responses/Forbidden.yaml' - '422': - $ref: '../components/responses/UnprocessableEntity.yaml' - '400': - $ref: '../components/responses/BadRequest.yaml' - '500': - $ref: '../components/responses/500.yaml' - '503': - $ref: '../components/responses/ServiceUnavailable.yaml' - '409': - $ref: '../components/responses/Conflict.yaml' /v3/apps/{guid}/manifest: get: summary: Generate a manifest for an app - description: Generate a manifest for an app and its underlying processes. + description: |- + Generate a manifest for an app and its underlying processes. + + The manifest is returned as a YAML document (`application/x-yaml`). See the response schema for the full manifest field reference. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer operationId: generateManifest tags: - - Manifests + - Manifests parameters: - - $ref: '../components/parameters/Guid.yaml' + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app responses: '200': description: OK content: application/x-yaml: schema: - type: string + $ref: ../components/schemas/Manifest.yaml + examples: + default: + summary: default + value: | + --- + applications: + - name: my-app + stack: cflinuxfs4 + features: + ssh: true + revisions: true + service-binding-k8s: false + file-based-vcap-services: false + services: + - my-service + routes: + - route: my-app.example.com + protocol: http1 + processes: + - type: web + instances: 2 + memory: 512M + log-rate-limit-per-second: 1KB + disk_quota: 1024M + health-check-type: http + health-check-http-endpoint: /healthy + health-check-invocation-timeout: 10 + health-check-interval: 5 + readiness-health-check-type: http + readiness-health-check-http-endpoint: /ready + readiness-health-check-invocation-timeout: 20 + readiness-health-check-interval: 5 + '400': + $ref: ../components/responses/BadRequest.yaml '401': - $ref: '../components/responses/Unauthorized.yaml' - '404': - $ref: '../components/responses/NotFound.yaml' + $ref: ../components/responses/Unauthorized.yaml '403': - $ref: '../components/responses/Forbidden.yaml' - '400': - $ref: '../components/responses/BadRequest.yaml' + $ref: ../components/responses/Forbidden.yaml + '404': + $ref: ../components/responses/NotFound.yaml + '409': + $ref: ../components/responses/Conflict.yaml + '422': + $ref: ../components/responses/UnprocessableEntity.yaml '500': - $ref: '../components/responses/500.yaml' + $ref: ../components/responses/500.yaml '502': - $ref: '../components/responses/BadGateway.yaml' + $ref: ../components/responses/BadGateway.yaml '503': - $ref: '../components/responses/ServiceUnavailable.yaml' - '422': - $ref: '../components/responses/UnprocessableEntity.yaml' - '409': - $ref: '../components/responses/Conflict.yaml' -/v3/spaces/{guid}/manifest_diff: - post: - summary: Create a manifest diff for a space (experimental) - description: 'This endpoint returns a JSON representation of the difference between - the provided manifest and the current state of a space. - - - Currently, this endpoint can only diff [version 1](#the-manifest-schema) manifests.' - operationId: createManifestDiff - tags: - - Manifests - parameters: - - $ref: '../components/parameters/Guid.yaml' - requestBody: - content: - application/x-yaml: - schema: - type: string - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - diff: - type: array - items: - type: object - properties: - op: - type: string - path: - type: string - was: - type: string - value: - type: string - '202': - description: Accepted - content: - application/json: - schema: - type: object - properties: - diff: - type: array - items: - type: object - properties: - op: - type: string - path: - type: string - was: - type: string - value: - type: string - '401': - $ref: '../components/responses/Unauthorized.yaml' - '404': - $ref: '../components/responses/NotFound.yaml' - '403': - $ref: '../components/responses/Forbidden.yaml' - '422': - $ref: '../components/responses/UnprocessableEntity.yaml' + $ref: ../components/responses/ServiceUnavailable.yaml diff --git a/docs/openapi/apis/cf/latest/paths/OrganizationQuotas.yaml b/docs/openapi/apis/cf/latest/paths/OrganizationQuotas.yaml index 9df1b0b11d8..4d99e59de9f 100644 --- a/docs/openapi/apis/cf/latest/paths/OrganizationQuotas.yaml +++ b/docs/openapi/apis/cf/latest/paths/OrganizationQuotas.yaml @@ -1,16 +1,30 @@ /v3/organization_quotas: get: summary: List organization quotas - description: This endpoint lists all organization quota resources. + description: |- + This endpoint lists all organization quota resources. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager *(response will only include guids of managed organizations)*, Org Auditor *(response will only include guids of audited organizations)*, Org Billing Manager *(response will only include guids of billing-managed organizations)*, Space Auditor *(response will only include guids of parent organizations)*, Space Developer *(response will only include guids of parent organizations)*, Space Manager *(response will only include guids of parent organizations)*, Space Supporter *(response will only include guids of parent organizations)* operationId: listOrganizationQuotas tags: - Organization Quotas 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` - name: guids in: query + required: false schema: type: array items: @@ -18,13 +32,15 @@ description: Comma-delimited list of organization quota guids to filter by - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of organization quota names to filter by + description: Comma-delimited list of organization quota names to filter by (case-insensitive) - name: organization_guids in: query + required: false schema: type: array items: @@ -53,7 +69,7 @@ next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: b7887f5c-34bb-40c5-9778-577572e4fb2d created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -75,11 +91,11 @@ relationships: organizations: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 9b370018-c38e-44c9-86d6-155c76801104 links: self: - href: https://api.example.org/v3/organization_quotas/quota-1-guid - - guid: 123e4567-e89b-12d3-a456-426614174000 + href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d + - guid: 1cfb4b53-71f2-4a6c-9c1c-53a6b0a1e2d4 created_at: '2017-05-04T17:00:41Z' updated_at: '2017-05-04T17:00:41Z' name: sancho-panza @@ -103,7 +119,7 @@ data: [] links: self: - href: https://api.example.org/v3/organization_quotas/quota-2-guid + href: https://api.example.org/v3/organization_quotas/1cfb4b53-71f2-4a6c-9c1c-53a6b0a1e2d4 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -126,6 +142,8 @@ This endpoint creates a new organization quota, but does not assign it to a specific organization unless an organization GUID is provided in the `relationships.organizations` parameter. To create an organization quota you must be an admin. + + **Permitted roles:** Admin operationId: createOrganizationQuota tags: - Organization Quotas @@ -142,7 +160,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b7887f5c-34bb-40c5-9778-577572e4fb2d created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -164,10 +182,10 @@ relationships: organizations: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 9b370018-c38e-44c9-86d6-155c76801104 links: self: - href: https://api.example.org/v3/organization_quotas/quota-guid + href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -185,12 +203,21 @@ /v3/organization_quotas/{guid}: get: summary: Get an organization quota - description: This endpoint gets an individual organization quota resource. + description: |- + This endpoint gets an individual organization quota resource. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager *(response will only include guids of managed organizations)*, Org Auditor *(response will only include guids of audited organizations)*, Org Billing Manager *(response will only include guids of billing-managed organizations)*, Space Auditor *(response will only include guids of parent organizations)*, Space Developer *(response will only include guids of parent organizations)*, Space Manager *(response will only include guids of parent organizations)*, Space Supporter *(response will only include guids of parent organizations)* operationId: getOrganizationQuota tags: - Organization Quotas parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization quota responses: '200': description: OK @@ -202,7 +229,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b7887f5c-34bb-40c5-9778-577572e4fb2d created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -224,10 +251,10 @@ relationships: organizations: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 9b370018-c38e-44c9-86d6-155c76801104 links: self: - href: https://api.example.org/v3/organization_quotas/quota-guid + href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -236,12 +263,21 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update an organization quota - description: This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. + description: |- + This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. + + **Permitted roles:** Admin operationId: updateOrganizationQuota tags: - Organization Quotas parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization quota requestBody: $ref: ../components/requestBodies/OrganizationQuotaUpdateRequestBody.yaml responses: @@ -255,7 +291,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b7887f5c-34bb-40c5-9778-577572e4fb2d created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -277,10 +313,10 @@ relationships: organizations: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 9b370018-c38e-44c9-86d6-155c76801104 links: self: - href: https://api.example.org/v3/organization_quotas/quota-guid + href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -299,12 +335,21 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete an organization quota - description: Organization quotas cannot be deleted when applied to any organizations. + description: |- + Organization quotas cannot be deleted when applied to any organizations. + + **Permitted roles:** Admin operationId: deleteOrganizationQuota tags: - Organization Quotas parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization quota responses: '202': description: Accepted @@ -314,6 +359,7 @@ schema: type: string format: uri + example: https://api.example.org/v3/jobs/af5c1a1f-0aeb-4d3a-a1f5-6e0d0a20e1b0 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -331,6 +377,8 @@ This endpoint applies an organization quota to one or more organizations. Only admin users can apply an organization quota to an organization. + + **Permitted roles:** Admin operationId: applyOrganizationQuota tags: - Organization Quotas @@ -341,36 +389,62 @@ schema: type: string format: uuid + description: The unique identifier for the organization quota requestBody: + description: The organizations that the organization quota will be applied to + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToMany.yaml + type: object + description: Request schema for applying an organization quota to organizations + properties: + data: + type: array + items: + $ref: ../components/schemas/Relationship.yaml + description: Organization guids that the quota will apply to + required: + - data examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f + - guid: 24637893-3b77-489d-bb79-8466f0d88b52 responses: '200': description: OK content: application/json: schema: - $ref: ../components/schemas/RelationshipToMany.yaml + type: object + description: The organizations the organization quota is applied to + properties: + data: + type: array + items: + $ref: ../components/schemas/Relationship.yaml + description: Organization guids that the quota applies to + links: + type: object + description: Links to related resources + properties: + self: + $ref: ../components/schemas/Link.yaml + description: The URL of this organization quota to organizations relationship examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f + - guid: 24637893-3b77-489d-bb79-8466f0d88b52 + - guid: 9b370018-c38e-44c9-86d6-155c76801104 links: self: - href: https://api.example.org/v3/organization_quotas/quota-guid/relationships/organizations + href: https://api.example.org/v3/organization_quotas/b7887f5c-34bb-40c5-9778-577572e4fb2d/relationships/organizations '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/Organizations.yaml b/docs/openapi/apis/cf/latest/paths/Organizations.yaml index 6312086350f..85cda24fabf 100644 --- a/docs/openapi/apis/cf/latest/paths/Organizations.yaml +++ b/docs/openapi/apis/cf/latest/paths/Organizations.yaml @@ -1,26 +1,43 @@ /v3/organizations: get: summary: List organizations - description: Retrieve all organizations the user has access to. + description: |- + Retrieve all organizations the user has access to. + + **Permitted roles:** All Roles operationId: listOrganizations tags: - Organizations 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 - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of organization names to filter by + description: Comma-delimited list of organization names to filter by (case-insensitive) - name: guids in: query + required: false schema: type: array items: @@ -47,7 +64,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 @@ -55,7 +72,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/885735b5-aea4-4cf5-8e44-961af0e41920 @@ -68,7 +85,7 @@ 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 @@ -76,7 +93,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 @@ -107,7 +124,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create an organization - description: Create an organization. + description: |- + Create an organization. + + **Permitted roles:** Admin, All Roles *(if the `user_org_creation` feature flag is enabled, any user with the `cloud_controller.write` scope can create organizations, but cannot set the `suspended` field to `true`)* operationId: createOrganization tags: - Organizations @@ -124,7 +144,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 24637893-3b77-489d-bb79-8466f0d88b52 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-organization @@ -132,7 +152,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/24637893-3b77-489d-bb79-8466f0d88b52 @@ -168,12 +188,21 @@ /v3/organizations/{guid}: get: summary: Get an organization - description: This endpoint retrieves the specified organization object. + description: |- + This endpoint retrieves the specified organization object. + + **Permitted roles:** All Roles operationId: getOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization responses: '200': description: OK @@ -185,7 +214,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 24637893-3b77-489d-bb79-8466f0d88b52 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-organization @@ -193,7 +222,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/24637893-3b77-489d-bb79-8466f0d88b52 @@ -211,7 +240,7 @@ operationId: getOrganizationQuota parameters: guid: $response.body#/relationships/quota/data/guid - description: Retrieve the quota associated with this organization + description: Retrieve the quota associated with this organization '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -220,12 +249,21 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update an organization - description: Update an organization. + description: |- + Update an organization. + + **Permitted roles:** Admin, Org Manager *(cannot change the `suspended` field)* operationId: updateOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization requestBody: $ref: ../components/requestBodies/OrganizationUpdateRequestBody.yaml responses: @@ -239,7 +277,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 24637893-3b77-489d-bb79-8466f0d88b52 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' name: my-organization @@ -247,7 +285,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/24637893-3b77-489d-bb79-8466f0d88b52 @@ -284,21 +322,31 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete an organization - description: When an organization is deleted, user roles associated with the organization will also be deleted. + description: |- + When an organization is deleted, user roles associated with the organization will also be deleted. + + **Permitted roles:** Admin operationId: deleteOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization responses: '202': description: Accepted headers: - location: - description: URL of the job to query the asynchronous operation + Location: + description: URL of the job that is deleting the organization schema: type: string format: uri + example: https://api.example.org/v3/jobs/af5c1a1f-0aeb-4d3a-a1f5-6e0d0a20e1b0 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -312,12 +360,21 @@ /v3/organizations/{guid}/domains/default: get: summary: Get default domain - description: Retrieve the default domain for a given organization. + description: |- + Retrieve the default domain for a given organization. + + **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: getDefaultDomainForOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization responses: '200': description: OK @@ -325,6 +382,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 '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -334,48 +423,28 @@ /v3/organizations/{guid}/usage_summary: get: summary: Get usage summary - description: This endpoint retrieves the specified organization object's memory and app instance usage summary. + description: |- + This endpoint retrieves the specified organization object's memory and app instance usage summary. + + **Permitted roles:** All Roles operationId: getUsageSummaryForOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization 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 - organization: - $ref: ../components/schemas/Link.yaml - description: The URL to get the organization for this usage summary + $ref: ../components/schemas/OrganizationUsageSummary.yaml examples: default: summary: default @@ -403,17 +472,37 @@ /v3/organizations/{guid}/users: get: summary: List users for an organization - description: Retrieve all users with a role in the specified organization. + description: |- + Retrieve all users with a role in the specified organization. + + **Permitted roles:** All Roles operationId: listUsersForOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization - $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` and `updated_at` - name: guids in: query + required: false schema: type: array items: @@ -421,25 +510,28 @@ description: Comma-delimited list of user guids to filter by - name: usernames in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of usernames to filter by + description: Comma-delimited list of usernames to filter by. Mutually exclusive with **partial_usernames** - name: origins in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of user origins to filter by + description: Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin "uaa"; users authenticated by an LDAP provider have the origin "ldap"; when filtering by origins, usernames must be included - name: partial_usernames in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of partial usernames to filter by + description: Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with **usernames** - $ref: ../components/parameters/LabelSelector.yaml - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml @@ -450,34 +542,84 @@ application/json: schema: $ref: ../components/schemas/UserList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/users?page=1&per_page=2 + last: + href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/users?page=2&per_page=2 + next: + href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/users?page=2&per_page=2 + previous: null + resources: + - guid: client_id + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + username: null + presentation_name: client_id + origin: null + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + - guid: 9da93b89-3f89-4f05-7238-8a2b123c79l9 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + username: some-name + presentation_name: some-name + origin: uaa + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9 '401': $ref: ../components/responses/Unauthorized.yaml '403': $ref: ../components/responses/Forbidden.yaml '404': $ref: ../components/responses/NotFound.yaml + '422': + $ref: ../components/responses/UnprocessableEntity.yaml /v3/organizations/{guid}/relationships/default_isolation_segment: get: summary: Get default isolation segment - description: Retrieve the default isolation segment for a given organization. + description: |- + Retrieve the default isolation segment for a given organization. + + **Permitted roles:** All Roles operationId: getDefaultIsolationSegmentForOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization responses: '200': description: OK content: application/json: schema: - $ref: ../components/schemas/RelationshipToOne.yaml + $ref: ../components/schemas/OrganizationDefaultIsolationSegmentRelationship.yaml examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment @@ -494,36 +636,55 @@ description: |- Set the default isolation segment for a given organization. Only isolation segments that are entitled to the organization are eligible to be the default isolation segment. - Apps will not run in the new default isolation segment until they are restarted. + > **Note:** Apps will not run in the new default isolation segment until they are restarted. + + **Permitted roles:** Admin, Org Manager operationId: assignDefaultIsolationSegmentForOrganization tags: - Organizations parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the organization requestBody: + description: The default isolation segment relationship to assign to the organization + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToOne.yaml + type: object + description: Request schema for assigning an organization's default isolation segment + properties: + data: + oneOf: + - $ref: ../components/schemas/Relationship.yaml + - type: 'null' + description: Isolation segment relationship; apps will run in this isolation segment; set data to `null` to remove the relationship + required: + - data examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 responses: '200': description: OK content: application/json: schema: - $ref: ../components/schemas/RelationshipToOne.yaml + $ref: ../components/schemas/OrganizationDefaultIsolationSegmentRelationship.yaml examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9d8e007c-ce52-4ea7-8a57-f2825d2c6b39 links: self: href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/relationships/default_isolation_segment diff --git a/docs/openapi/apis/cf/latest/paths/Packages.yaml b/docs/openapi/apis/cf/latest/paths/Packages.yaml index 0986f03c768..27809f6b5bf 100644 --- a/docs/openapi/apis/cf/latest/paths/Packages.yaml +++ b/docs/openapi/apis/cf/latest/paths/Packages.yaml @@ -1,19 +1,33 @@ /v3/packages: get: summary: List packages - description: Retrieve all packages. + description: |- + Retrieve all packages the user has access to. + + **Permitted roles:** All Roles operationId: listPackages tags: - Packages 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 - name: guids in: query + required: false schema: type: array items: @@ -21,6 +35,7 @@ description: Comma-delimited list of package guids to filter by - name: states in: query + required: false schema: type: array items: @@ -35,6 +50,7 @@ description: Comma-delimited list of package states to filter by - name: types in: query + required: false schema: type: array items: @@ -45,6 +61,7 @@ description: Comma-delimited list of package types to filter by - name: app_guids in: query + required: false schema: type: array items: @@ -52,6 +69,7 @@ description: Comma-delimited list of app guids to filter by - name: space_guids in: query + required: false schema: type: array items: @@ -59,6 +77,7 @@ description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false schema: type: array items: @@ -79,13 +98,13 @@ total_results: 2 total_pages: 1 first: - href: https://api.example.org?types=bits%2Cdocker&page=1&per_page=2 + href: https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2 last: - href: https://api.example.org?types=bits%2Cdocker&page=1&per_page=2 + href: https://api.example.org/v3/packages?types=bits%2Cdocker&page=1&per_page=2 next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: a57fd932-85db-483a-a27e-b00efbb3b0a4 type: bits data: checksum: @@ -98,7 +117,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: fa3558ce-1c4d-46fc-9776-54b9c8021745 links: self: href: https://api.example.org/v3/packages/a57fd932-85db-483a-a27e-b00efbb3b0a4 @@ -113,7 +132,7 @@ metadata: labels: {} annotations: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691 type: docker data: image: registry/image:latest @@ -125,7 +144,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: fa3558ce-1c4d-46fc-9776-54b9c8021745 links: self: href: https://api.example.org/v3/packages/8f1f294d-cef8-4c11-9f0b-3bcdc0bd2691 @@ -151,25 +170,69 @@ '503': $ref: ../components/responses/ServiceUnavailable.yaml post: - summary: Create a package - description: Create a package. + summary: Create or copy a package + description: |- + Create a package. + + **Copy a package:** supplying the optional `source_guid` query parameter copies the bits of the source package identified by `source_guid` to a target package instead of creating a new package. In copy mode `type` and `data` are not accepted; `relationships.app`, a relationship to the destination app, is the only accepted body parameter. + + **Permitted roles:** Admin, Space Developer operationId: createPackage tags: - Packages + parameters: + - name: source_guid + in: query + required: false + schema: + type: string + format: uuid + description: GUID of the source package to copy from. When supplied, the bits of that package are copied to a new package for the app given in `relationships.app` requestBody: $ref: ../components/requestBodies/PackageCreateRequestBody.yaml responses: '201': - description: Successfully created package + description: Successfully created (or copied) package content: application/json: schema: $ref: ../components/schemas/Package.yaml examples: + buildpack_app: + summary: buildpack app + value: + guid: 44f7c078-0934-470f-9883-4fcddc5b8f13 + type: bits + data: + checksum: + type: sha256 + value: null + error: null + state: AWAITING_UPLOAD + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + relationships: + app: + data: + guid: 1d3bf0ec-5806-43c4-b64e-8364dba1086a + links: + self: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13 + upload: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload + method: POST + download: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download + method: GET + app: + href: https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a + metadata: + labels: {} + annotations: {} docker_app: summary: Docker app value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 4cb65058-f04f-458f-aca1-5f4e43de6407 type: docker data: image: registry/image:latest @@ -181,7 +244,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: d8b8148d-5798-44de-821a-64b85b15e968 links: self: href: https://api.example.org/v3/packages/4cb65058-f04f-458f-aca1-5f4e43de6407 @@ -190,6 +253,28 @@ metadata: labels: {} annotations: {} + copy: + summary: copy (with the source_guid query parameter) + value: + guid: fec72fc1-e453-4463-a86d-5df426f337a3 + type: docker + data: + image: http://awesome-sauce.example.org + state: COPYING + created_at: '2016-03-17T21:41:09Z' + updated_at: '2016-06-08T16:41:26Z' + relationships: + app: + data: + guid: 36208a68-562d-4f51-94ea-28bd8553a271 + links: + self: + href: https://api.example.org/v3/packages/fec72fc1-e453-4463-a86d-5df426f337a3 + app: + href: https://api.example.org/v3/apps/36208a68-562d-4f51-94ea-28bd8553a271 + metadata: + labels: {} + annotations: {} links: app: operationId: getApp @@ -213,7 +298,10 @@ /v3/packages/{guid}: get: summary: Get a package - description: Retrieve a package. + description: |- + Retrieve a package. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getPackage tags: - Packages @@ -226,6 +314,38 @@ application/json: schema: $ref: ../components/schemas/Package.yaml + examples: + default: + summary: default + value: + guid: 44f7c078-0934-470f-9883-4fcddc5b8f13 + type: bits + data: + checksum: + type: sha256 + value: null + error: null + state: PROCESSING_UPLOAD + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + relationships: + app: + data: + guid: 1d3bf0ec-5806-43c4-b64e-8364dba1086a + links: + self: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13 + upload: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload + method: POST + download: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download + method: GET + app: + href: https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a + metadata: + labels: {} + annotations: {} links: app: operationId: getApp @@ -242,37 +362,17 @@ $ref: ../components/responses/UnprocessableEntity.yaml patch: summary: Update a package - description: Update a package. + description: |- + Update a package. + + **Permitted roles:** Admin, Space Developer operationId: updatePackage tags: - Packages parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: Package object that needs to be updated - required: true - content: - application/json: - schema: - type: object - properties: - metadata: - $ref: ../components/schemas/Metadata.yaml - username: - type: string - description: The username for the image’s registry. Only possible for Docker package. - password: - type: string - description: The password for the image’s registry. Only possible for Docker package. - examples: - default: - summary: default - value: - metadata: - labels: - key: value - annotations: - note: detailed information + $ref: ../components/requestBodies/PackageUpdateRequestBody.yaml responses: '200': description: Successfully updated package @@ -280,6 +380,40 @@ application/json: schema: $ref: ../components/schemas/Package.yaml + examples: + default: + summary: default + value: + guid: 44f7c078-0934-470f-9883-4fcddc5b8f13 + type: bits + data: + checksum: + type: sha256 + value: null + error: null + state: PROCESSING_UPLOAD + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + relationships: + app: + data: + guid: 1d3bf0ec-5806-43c4-b64e-8364dba1086a + links: + self: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13 + upload: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload + method: POST + download: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download + method: GET + app: + href: https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a + metadata: + labels: + key: value + annotations: + note: detailed information '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -298,7 +432,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a package - description: Delete a package. + description: |- + Delete a package. + + **Permitted roles:** Admin, Space Developer operationId: deletePackage tags: - Packages @@ -326,7 +463,10 @@ /v3/packages/{guid}/droplets: get: summary: List droplets for a package - description: Retrieve a list of droplets belonging to a package. + description: |- + Retrieve a list of droplets belonging to a package. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listPackageDroplets tags: - Packages @@ -335,10 +475,21 @@ - $ref: ../components/parameters/Guid.yaml - $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` and `updated_at` - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: @@ -346,10 +497,18 @@ description: Comma-delimited list of droplet guids to filter by - name: states in: query + required: false schema: type: array items: type: string + enum: + - AWAITING_UPLOAD + - PROCESSING_UPLOAD + - STAGED + - COPYING + - FAILED + - EXPIRED description: Comma-delimited list of droplet states to filter by responses: '200': @@ -366,13 +525,13 @@ total_results: 2 total_pages: 1 first: - href: https://api.example.org?page=1&per_page=50 + href: https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50 last: - href: https://api.example.org?page=1&per_page=50 + href: https://api.example.org/v3/packages/7b34f1cf-7e73-428a-bb5a-8a17a8058396/droplets?page=1&per_page=50 next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 585bc3c1-3743-497d-88b0-403ad6b56d16 state: STAGED error: null lifecycle: @@ -381,7 +540,7 @@ image: null execution_metadata: PRIVATE DATA HIDDEN process_types: - redacted_message: 123e4567-e89b-12d3-a456-426614174000 + redacted_message: '[PRIVATE DATA HIDDEN IN LISTS]' checksum: type: sha256 value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 @@ -396,7 +555,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/585bc3c1-3743-497d-88b0-403ad6b56d16 @@ -412,15 +571,15 @@ metadata: labels: {} annotations: {} - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fdf3851c-def8-4de1-87f1-6d4543189e22 state: STAGED error: null lifecycle: type: docker data: {} - execution_metadata: 123e4567-e89b-12d3-a456-426614174000 + execution_metadata: '[PRIVATE DATA HIDDEN IN LISTS]' process_types: - redacted_message: 123e4567-e89b-12d3-a456-426614174000 + redacted_message: '[PRIVATE DATA HIDDEN IN LISTS]' image: cloudfoundry/diego-docker-app-custom:latest checksum: null buildpacks: null @@ -430,7 +589,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7b34f1cf-7e73-428a-bb5a-8a17a8058396 links: self: href: https://api.example.org/v3/droplets/fdf3851c-def8-4de1-87f1-6d4543189e22 @@ -453,53 +612,19 @@ /v3/packages/{guid}/upload: post: summary: Upload package bits - description: This upload endpoint takes a multi-part form requests for packages of type `bits`. The request requires either a [.zip file](https://en.wikipedia.org/wiki/Zip_(file_format)) uploaded under the `bits` field or a list of [resource match objects](#the-resource-match-object) under the `resources` field. These field may be used together. + description: |- + This upload endpoint takes a multi-part form requests for packages of type `bits`. The request requires either a [.zip file](https://en.wikipedia.org/wiki/Zip_(file_format)) uploaded under the `bits` field or a list of [resource match objects](#the-resource-match-object) under the `resources` field. These field may be used together. + + The `resources` field in the request accepts the v2 resources object format. + + **Permitted roles:** Admin, Space Developer operationId: uploadPackageBits tags: - Packages parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - content: - multipart/form-data: - schema: - type: object - properties: - bits: - type: string - format: binary - resources: - type: array - items: - type: object - properties: - path: - type: string - size_in_bytes: - type: integer - checksum: - type: object - properties: - value: - type: string - application/json: - schema: - type: object - properties: - resources: - type: array - items: - type: object - properties: - path: - type: string - size_in_bytes: - type: integer - checksum: - type: object - properties: - value: - type: string + $ref: ../components/requestBodies/PackageUploadRequestBody.yaml responses: '200': description: Successfully uploaded package bits @@ -507,17 +632,38 @@ application/json: schema: $ref: ../components/schemas/Package.yaml - '202': - description: Upload initiated - headers: - Location: - schema: - type: string - description: URL of the job tracking the upload - content: - application/json: - schema: - $ref: ../components/schemas/Package.yaml + examples: + default: + summary: default + value: + guid: 44f7c078-0934-470f-9883-4fcddc5b8f13 + type: bits + data: + checksum: + type: sha256 + value: null + error: null + state: PROCESSING_UPLOAD + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + relationships: + app: + data: + guid: 1d3bf0ec-5806-43c4-b64e-8364dba1086a + links: + self: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13 + upload: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/upload + method: POST + download: + href: https://api.example.org/v3/packages/44f7c078-0934-470f-9883-4fcddc5b8f13/download + method: GET + app: + href: https://api.example.org/v3/apps/1d3bf0ec-5806-43c4-b64e-8364dba1086a + metadata: + labels: {} + annotations: {} '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -533,53 +679,30 @@ This endpoint downloads the bits of an existing package. When using a remote blobstore, such as AWS, the response is a redirect to the actual location of the bits. If the client is automatically following redirects, then the OAuth token that was used to communicate with Cloud Controller will be replayed on the new redirect request. Some blobstores may reject the request in that case. Clients may need to follow the redirect without including the OAuth token. + + **Permitted roles:** Admin, Space Developer operationId: downloadPackageBits tags: - Packages parameters: - $ref: ../components/parameters/Guid.yaml responses: - '302': - description: Redirect to download location - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml -/v3/packages?source_guid={source_guid}: - post: - summary: Copy a package - description: This endpoint copies the bits of a source package to a target package. - operationId: copyPackage - tags: - - Packages - parameters: - - name: source_guid - in: query - required: true - schema: - type: string - format: uuid - description: The GUID of the package to copy from - requestBody: - description: Destination app for the copied package - required: true - content: - application/json: - schema: - type: object - properties: - relationships: - $ref: ../components/schemas/Relationships.yaml - required: - - relationships - description: Request schema for copying a package - responses: - '201': - description: Successfully copied package + '200': + description: The package bits; returned directly when the blobstore is local to the Cloud Controller content: - application/json: + application/octet-stream: schema: - $ref: ../components/schemas/Package.yaml + type: string + format: binary + description: A zip file containing the package bits + '302': + description: Redirect to the actual location of the bits in the remote blobstore + headers: + Location: + description: URL of the package bits in the blobstore + schema: + type: string + format: uri '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -588,27 +711,46 @@ $ref: ../components/responses/NotFound.yaml '422': $ref: ../components/responses/UnprocessableEntity.yaml + '502': + $ref: ../components/responses/BadGateway.yaml /v3/apps/{guid}/packages: get: summary: List packages for an app - description: Retrieve packages for an app that the user has access to. + description: |- + Retrieve packages for an app that the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppPackages tags: - Packages parameters: - $ref: ../components/parameters/Guid.yaml + - $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/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml - name: guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app GUIDs to filter by - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml + description: Comma-delimited list of package guids to filter by - name: states in: query + required: false schema: type: array items: @@ -623,6 +765,7 @@ description: Comma-delimited list of package states to filter by - name: types in: query + required: false schema: type: array items: @@ -652,7 +795,7 @@ next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 752edab0-2147-4f58-9c25-cd72ad8c3561 type: bits data: error: null @@ -665,7 +808,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: f2efe391-2b5b-4836-8518-ad93fa9ebf69 links: self: href: https://api.example.org/v3/packages/752edab0-2147-4f58-9c25-cd72ad8c3561 diff --git a/docs/openapi/apis/cf/latest/paths/Processes.yaml b/docs/openapi/apis/cf/latest/paths/Processes.yaml index 278fa7f5eed..886dd6191a2 100644 --- a/docs/openapi/apis/cf/latest/paths/Processes.yaml +++ b/docs/openapi/apis/cf/latest/paths/Processes.yaml @@ -1,19 +1,22 @@ /v3/processes: get: summary: List processes - description: Retrieve all processes. + description: |- + Retrieve all processes the user has access to. + + **Permitted roles:** All Roles operationId: listProcesses tags: - Processes parameters: - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: @@ -21,6 +24,7 @@ description: Comma-delimited list of process guids to filter by - name: types in: query + required: false schema: type: array items: @@ -28,6 +32,7 @@ description: Comma-delimited list of process types to filter by - name: app_guids in: query + required: false schema: type: array items: @@ -35,6 +40,7 @@ description: Comma-delimited list of app guids to filter by - name: space_guids in: query + required: false schema: type: array items: @@ -42,11 +48,31 @@ description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by + - 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` + - name: embed + in: query + required: false + schema: + type: string + enum: + - process_instances + description: Comma-delimited list of resources to embed in the response. Valid values are `process_instances`. See [embed](#embed) for more details. This parameter is experimental. responses: '200': description: OK @@ -54,6 +80,111 @@ application/json: schema: $ref: ../components/schemas/ProcessList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/processes?page=1&per_page=2 + last: + href: https://api.example.org/v3/processes?page=2&per_page=2 + next: + href: https://api.example.org/v3/processes?page=2&per_page=2 + previous: null + resources: + - guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: '[PRIVATE DATA HIDDEN IN LISTS]' + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + invocation_timeout: null + interval: null + readiness_health_check: + type: process + data: + invocation_timeout: null + interval: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances + - guid: 3fccacd9-4b02-4b96-8d02-8e865865e9eb + type: worker + command: '[PRIVATE DATA HIDDEN IN LISTS]' + user: vcap + instances: 1 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: process + data: + invocation_timeout: null + interval: null + readiness_health_check: + type: http + data: + endpoint: /ready + invocation_timeout: 2 + interval: 5 + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: null + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: 74e513bb-7b9e-445c-84d5-7fea1394e611 + links: + self: + href: https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb + scale: + href: https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/stats + process_instances: + href: https://api.example.org/v3/processes/3fccacd9-4b02-4b96-8d02-8e865865e9eb/process_instances '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -73,12 +204,23 @@ /v3/processes/{guid}: get: summary: Get a process - description: Get a process. + description: |- + Retrieve a process. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(some fields are redacted)*, Org Manager *(some fields are redacted)*, Space Auditor *(some fields are redacted)*, Space Developer, Space Manager *(some fields are redacted)*, Space Supporter *(some fields are redacted)* operationId: getProcess tags: - Processes parameters: - $ref: ../components/parameters/Guid.yaml + - name: embed + in: query + required: false + schema: + type: string + enum: + - process_instances + description: Comma-delimited list of resources to embed in the response. Valid values are `process_instances`. See [embed](#embed) for more details. This parameter is experimental. responses: '200': description: OK @@ -90,7 +232,53 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: rackup + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + readiness_health_check: + type: process + data: + invocation_timeout: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances + embedded_process_instances: + summary: with embedded process instances + value: + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 type: web command: rackup user: vcap @@ -119,10 +307,10 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 revision: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 metadata: labels: {} annotations: {} @@ -162,7 +350,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a process - description: Update a process. + description: |- + Update a process. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: updateProcess tags: - Processes @@ -177,6 +368,55 @@ application/json: schema: $ref: ../components/schemas/Process.yaml + examples: + default: + summary: default + value: + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: rackup + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + readiness_health_check: + type: process + data: + invocation_timeout: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: + key: value + annotations: + note: detailed information + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances links: app: operationId: getApp @@ -206,8 +446,11 @@ $ref: ../components/responses/ServiceUnavailable.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. + summary: Get process instances for a process (experimental) + description: |- + This endpoint retrieves the instances for a process. This is a pseudo-resource that provides a lightweight view of process instance states, containing only the `index`, `state`, and `since` fields. Unlike the full [process stats](#get-stats-for-a-process) endpoint, this endpoint is designed for embedding into process resources and provides a minimal representation. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listProcessInstances tags: - Processes @@ -219,32 +462,7 @@ 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 + $ref: ../components/schemas/ProcessInstanceList.yaml examples: default: summary: default @@ -273,7 +491,10 @@ /v3/processes/{guid}/stats: get: summary: Get stats for a process - description: Get stats for a process. + description: |- + Process stats are objects that represent the individual instances of a process. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(some fields are redacted)*, Org Manager *(some fields are redacted)*, Space Auditor *(some fields are redacted)*, Space Developer, Space Manager *(some fields are redacted)*, Space Supporter *(some fields are redacted)* operationId: getProcessStats tags: - Processes @@ -293,7 +514,7 @@ resources: - type: web index: 0 - instance_guid: 123e4567-e89b-12d3-a456-426614174000 + instance_guid: e49f448e-54d2-4c33-61a3-5335 state: RUNNING routable: true usage: @@ -349,45 +570,17 @@ /v3/processes/{guid}/actions/scale: post: summary: Scale a process - description: Scale a process. + description: |- + Scale a process. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: scaleProcess tags: - Processes parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - content: - application/json: - schema: - properties: - instances: - type: - - integer - - 'null' - description: The number of instances to run - memory_in_mb: - type: - - integer - - 'null' - 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 - examples: - default: - summary: default - value: - instances: 5 - memory_in_mb: 256 - disk_in_mb: 1024 - log_rate_limit_in_bytes_per_second: 1024 + $ref: ../components/requestBodies/ProcessScaleRequestBody.yaml responses: '202': description: Accepted @@ -395,6 +588,53 @@ application/json: schema: $ref: ../components/schemas/Process.yaml + examples: + default: + summary: default + value: + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: rackup + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + readiness_health_check: + type: process + data: + invocation_timeout: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -418,6 +658,8 @@ Terminate an instance of a specific process. Health management will eventually restart the instance. This allows a user to stop a single misbehaving instance of a process. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: terminateProcessInstance tags: - Processes @@ -428,6 +670,7 @@ required: true schema: type: integer + description: The zero-based index of the process instance responses: '204': description: No Content @@ -443,16 +686,62 @@ $ref: ../components/responses/500.yaml /v3/apps/{guid}/processes: get: - summary: List processes for an app - description: Retrieves all processes belonging to an app. + summary: List processes for app + description: |- + Retrieves all processes belonging to an app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppProcesses tags: - Processes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml + - $ref: ../components/parameters/LabelSelector.yaml + - name: guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of process guids to filter by + - name: types + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of process types to filter by + - 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` + - name: embed + in: query + required: false + schema: + type: string + enum: + - process_instances + description: Comma-delimited list of resources to embed in the response. Valid values are `process_instances`. See [embed](#embed) for more details. This parameter is experimental. responses: '200': description: OK @@ -460,26 +749,109 @@ application/json: schema: $ref: ../components/schemas/ProcessList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=1&per_page=2 + last: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2 + next: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/processes?page=2&per_page=2 + previous: null + resources: + - guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: '[PRIVATE DATA HIDDEN IN LISTS]' + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + invocation_timeout: null + interval: null + readiness_health_check: + type: process + data: + invocation_timeout: null + interval: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances + '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 /v3/apps/{guid}/processes/{type}: get: summary: Get a process for an app - description: Get a specific process for an app. + description: |- + Retrieve a process by type for an app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(some fields are redacted)*, Org Manager *(some fields are redacted)*, Space Auditor *(some fields are redacted)*, Space Developer, Space Manager *(some fields are redacted)*, Space Supporter *(some fields are redacted)* operationId: getProcessForApp tags: - Processes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - name: type in: path required: true schema: type: string + description: Process type; a unique identifier for processes belonging to an app + - name: embed + in: query + required: false + schema: + type: string + enum: + - process_instances + description: Comma-delimited list of resources to embed in the response. Valid values are `process_instances`. See [embed](#embed) for more details. This parameter is experimental. responses: '200': description: OK @@ -487,6 +859,53 @@ application/json: schema: $ref: ../components/schemas/Process.yaml + examples: + default: + summary: default + value: + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: rackup + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + readiness_health_check: + type: process + data: + invocation_timeout: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -495,17 +914,27 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a process for an app - description: Update a specific process for an app. + description: |- + Update a process by type for an app. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: updateProcessForApp tags: - Processes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - name: type in: path required: true schema: type: string + description: Process type; a unique identifier for processes belonging to an app requestBody: $ref: ../components/requestBodies/ProcessUpdateRequestBody.yaml responses: @@ -515,6 +944,55 @@ application/json: schema: $ref: ../components/schemas/Process.yaml + examples: + default: + summary: default + value: + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: rackup + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + readiness_health_check: + type: process + data: + invocation_timeout: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: + key: value + annotations: + note: detailed information + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -528,17 +1006,27 @@ /v3/apps/{guid}/processes/{type}/stats: get: summary: Get stats for a process for an app - description: Get stats for a specific process for an app. + description: |- + Process stats are objects that represent the individual instances of a process. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(some fields are redacted)*, Org Manager *(some fields are redacted)*, Space Auditor *(some fields are redacted)*, Space Developer, Space Manager *(some fields are redacted)*, Space Supporter *(some fields are redacted)* operationId: getProcessStatsForApp tags: - Processes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - name: type in: path required: true schema: type: string + description: Process type; a unique identifier for processes belonging to an app responses: '200': description: OK @@ -546,6 +1034,37 @@ application/json: schema: $ref: ../components/schemas/ProcessStats.yaml + examples: + default: + summary: default + value: + resources: + - type: web + index: 0 + instance_guid: e49f448e-54d2-4c33-61a3-5335 + state: RUNNING + routable: true + usage: + time: '2016-03-23T23:17:30.476314154Z' + cpu: 0.00038711029163348665 + cpu_entitlement: 0.01117396940977856 + mem: 19177472 + disk: 69705728 + log_rate: 0 + host: 10.244.16.10 + instance_internal_ip: 10.255.93.167 + instance_ports: + - external: 64546 + internal: 8080 + external_tls_proxy_port: 61002 + internal_tls_proxy_port: 61003 + uptime: 9042 + mem_quota: 268435456 + disk_quota: 1073741824 + fds_quota: 16384 + isolation_segment: example_iso_segment + log_rate_limit: null + details: null '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -557,42 +1076,29 @@ /v3/apps/{guid}/processes/{type}/actions/scale: post: summary: Scale a process for an app - description: Scale a specific process for an app. + description: |- + Scale a process by type for an app. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: scaleProcessForApp tags: - Processes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - name: type in: path required: true schema: type: string + description: Process type; a unique identifier for processes belonging to an app requestBody: - content: - application/json: - schema: - properties: - instances: - type: - - integer - - 'null' - description: The number of instances to run - memory_in_mb: - type: - - integer - - 'null' - 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 + $ref: ../components/requestBodies/ProcessScaleRequestBody.yaml responses: '202': description: Accepted @@ -600,6 +1106,55 @@ application/json: schema: $ref: ../components/schemas/Process.yaml + examples: + default: + summary: default + value: + guid: 6a901b7c-9417-4dc1-8189-d3234aa0ab82 + type: web + command: rackup + user: vcap + instances: 5 + memory_in_mb: 256 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + health_check: + type: port + data: + timeout: null + readiness_health_check: + type: process + data: + invocation_timeout: null + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + revision: + data: + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + metadata: + labels: {} + annotations: {} + created_at: '2016-03-23T18:48:22Z' + updated_at: '2016-03-23T18:48:42Z' + version: e9df685c-0464-4aa7-b5f0-8ed843077c13 + links: + self: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82 + scale: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/actions/scale + method: POST + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + space: + href: https://api.example.org/v3/spaces/2f35885d-0c9d-4423-83ad-fd05066f8576 + stats: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/stats + process_instances: + href: https://api.example.org/v3/processes/6a901b7c-9417-4dc1-8189-d3234aa0ab82/process_instances + '400': + $ref: ../components/responses/BadRequest.yaml '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -611,22 +1166,35 @@ /v3/apps/{guid}/processes/{type}/instances/{index}: delete: summary: Terminate a process instance for an app - description: Terminate a specific process instance for an app. + description: |- + Terminate an instance of a specific process. Health management will eventually restart the instance. + + This allows a user to stop a single misbehaving instance of a process. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: terminateProcessInstanceForApp tags: - Processes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - name: type in: path required: true schema: type: string + description: Process type; a unique identifier for processes belonging to an app - name: index in: path required: true schema: type: integer + description: The zero-based index of the process instance responses: '204': description: No Content diff --git a/docs/openapi/apis/cf/latest/paths/ResourceMatches.yaml b/docs/openapi/apis/cf/latest/paths/ResourceMatches.yaml index 3cf82d8fda6..d2ea3d3cf2d 100644 --- a/docs/openapi/apis/cf/latest/paths/ResourceMatches.yaml +++ b/docs/openapi/apis/cf/latest/paths/ResourceMatches.yaml @@ -11,32 +11,18 @@ Cloud Foundry operators may set minimum/maximum file sizes to match against. If the file size provided is outside this range, it will not be matched against. If the `resource_matching` [feature flag](#the-feature-flag-object) is disabled, resource matching will always return an empty array. + + **Permitted roles:** All Roles operationId: postResourceMatches tags: - Resource Matches requestBody: + description: List of resources to check for in the resource cache + required: true content: application/json: schema: - type: object - properties: - resources: - type: array - items: - type: object - properties: - checksum: - type: object - properties: - value: - type: string - size_in_bytes: - type: integer - path: - type: string - description: List of resources to check for in the resource cache - required: - - resources + $ref: ../components/schemas/ResourceMatch.yaml examples: default: summary: default diff --git a/docs/openapi/apis/cf/latest/paths/Revisions.yaml b/docs/openapi/apis/cf/latest/paths/Revisions.yaml index a98e3025033..7d598abfe4b 100644 --- a/docs/openapi/apis/cf/latest/paths/Revisions.yaml +++ b/docs/openapi/apis/cf/latest/paths/Revisions.yaml @@ -1,12 +1,16 @@ /v3/revisions/{guid}: get: summary: Get a revision - description: Retrieve a revision. + description: |- + Retrieve a revision. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getRevision tags: - Revisions parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the revision responses: '200': description: Successfully retrieved revision @@ -14,6 +18,41 @@ application/json: schema: $ref: ../components/schemas/Revision.yaml + examples: + default: + summary: default + value: + guid: 123e4567-e89b-12d3-a456-426614174000 + version: 1 + droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + processes: + web: + command: bundle exec rackup + sidecars: + - name: auth-sidecar + command: bundle exec sidecar + process_types: + - web + memory_in_mb: 300 + description: Initial revision. + deployable: true + relationships: + app: + data: + guid: 123e4567-e89b-12d3-a456-426614174000 + created_at: '2017-02-01T01:33:58Z' + updated_at: '2017-02-01T01:33:58Z' + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920 + app: + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 + environment_variables: + href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables links: app: operationId: getApp @@ -40,12 +79,16 @@ $ref: ../components/responses/ServiceUnavailable.yaml patch: summary: Update a revision - description: Update a revision. + description: |- + Update a revision. + + **Permitted roles:** Admin, Space Developer operationId: updateRevision tags: - Revisions parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the revision requestBody: description: Revision object that needs to be updated required: true @@ -56,6 +99,10 @@ properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the revision + + `annotations`: Annotations applied to the revision description: Request schema for updating a revision examples: default: @@ -73,6 +120,43 @@ application/json: schema: $ref: ../components/schemas/Revision.yaml + examples: + default: + summary: default + value: + guid: 123e4567-e89b-12d3-a456-426614174000 + version: 1 + droplet: + guid: 123e4567-e89b-12d3-a456-426614174000 + processes: + web: + command: bundle exec rackup + sidecars: + - name: auth-sidecar + command: bundle exec sidecar + process_types: + - web + memory_in_mb: 300 + description: Initial revision. + deployable: true + relationships: + app: + data: + guid: 123e4567-e89b-12d3-a456-426614174000 + created_at: '2017-02-01T01:33:58Z' + updated_at: '2017-02-01T01:33:58Z' + metadata: + labels: + key: value + annotations: + note: detailed information + links: + self: + href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920 + app: + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446 + environment_variables: + href: https://api.example.org/v3/revisions/885735b5-aea4-4cf5-8e44-961af0e41920/environment_variables links: app: operationId: getApp @@ -98,12 +182,16 @@ /v3/revisions/{guid}/environment_variables: get: summary: Get environment variables for a revision - description: Retrieve the environment variables that are associated with the revision. + description: |- + Retrieve the environment variables that are associated with the revision. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer operationId: getRevisionEnvironmentVariables tags: - Revisions parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the revision responses: '200': description: Successfully retrieved revision environment variables @@ -111,21 +199,26 @@ application/json: schema: type: object + description: The environment variables associated with the revision properties: var: type: object - description: Environment variables for the revision + description: The environment variables that were set on the app at this revision additionalProperties: type: string links: type: object + description: Links to related resources properties: self: $ref: ../components/schemas/Link.yaml + description: The URL to get the environment variables for this revision revision: $ref: ../components/schemas/Link.yaml + description: The URL to get the revision app: $ref: ../components/schemas/Link.yaml + description: The URL to get the app the revision is associated with examples: default: summary: default @@ -148,25 +241,46 @@ /v3/apps/{guid}/revisions: get: summary: List revisions for an app - description: Retrieve revisions for an app the user has access to. + description: |- + Retrieve revisions for an app the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listRevisionsForApp tags: - Revisions parameters: - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/LabelSelector.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml + description: The GUID of the app - name: versions in: query + required: false schema: type: array items: type: string description: Comma-delimited list of revision versions to filter by + - $ref: ../components/parameters/LabelSelector.yaml + - $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/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml + - name: deployable + in: query + required: false + schema: + type: boolean + description: Filter by whether the revision's droplet is staged and the revision can be used to [create a deployment](#create-a-deployment); valid values are `true` and `false` responses: '200': description: Successfully retrieved revisions for app @@ -228,15 +342,30 @@ /v3/apps/{guid}/revisions/deployed: get: summary: List deployed revisions for an app - description: Retrieve deployed revisions for an app the user has access to. Deployed revisions are revisions that are linked to started processes in the app. + description: |- + Retrieve deployed revisions for an app the user has access to. + Deployed revisions are revisions that are linked to started processes in the app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listDeployedRevisionsForApp tags: - Revisions parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the app - $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` responses: '200': description: Successfully retrieved deployed revisions for app @@ -252,9 +381,9 @@ total_results: 1 total_pages: 1 first: - href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50 + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed?page=1&per_page=50 last: - href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions?page=1&per_page=50 + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/revisions/deployed?page=1&per_page=50 next: null previous: null resources: diff --git a/docs/openapi/apis/cf/latest/paths/Roles.yaml b/docs/openapi/apis/cf/latest/paths/Roles.yaml index 4742d278b75..82fe60466f1 100644 --- a/docs/openapi/apis/cf/latest/paths/Roles.yaml +++ b/docs/openapi/apis/cf/latest/paths/Roles.yaml @@ -1,17 +1,29 @@ /v3/roles: get: summary: List roles - description: This endpoint lists roles that the user has access to. + description: |- + This endpoint lists roles that the user has access to. + + **Permitted roles:** All Roles operationId: listRoles tags: - Roles 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 - name: guids in: query description: Comma-delimited list of role guids to filter by @@ -21,7 +33,7 @@ type: string - name: types in: query - description: Comma-delimited list of role types to filter by + description: Comma-delimited list of [role types](#valid-role-types) to filter by schema: type: array items: @@ -35,16 +47,16 @@ - space_developer - space_manager - space_supporter - - name: organization_guids + - name: space_guids in: query - description: Comma-delimited list of organization guids to filter by + description: Comma-delimited list of space guids to filter by schema: type: array items: type: string - - name: space_guids + - name: organization_guids in: query - description: Comma-delimited list of space guids to filter by + description: Comma-delimited list of organization guids to filter by schema: type: array items: @@ -58,7 +70,7 @@ type: string - name: include in: query - description: Optionally include additional related resources in the response; valid values are `user`, `space`, and `organization`. + description: Optionally include a list of unique related resources in the response; valid values are `user`, `space`, and `organization` schema: type: array items: @@ -97,9 +109,12 @@ For a user to be assigned a space role, the user must already have an organization role in the parent organization. - If the associated user is valid but does not exist in Cloud Controller’s database, a user resource will be created automatically. + If the associated user does not exist in Cloud Controller's database, a user resource will be created automatically. This user may correspond to a UAA user or client. See the [user resource](#users) for more details. + + If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, the organization role is being created by username + origin and the user does not exist in UAA yet, the user will be created. + The origin must be different from `uaa` in this case. - If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, the organization role is being created by username + origin and the user does not exist in UAA yet, the user will be created. The origin must be different from `uaa` in this case. + **Permitted roles:** Admin, Org Manager *(Can create roles in managed organizations and spaces within those organizations; can also create roles for users outside of managed organizations when `set_roles_by_username` [feature_flag](#list-of-feature-flags) is enabled; this requires identifying users by username and origin)*, Space Manager *(Can create roles in managed spaces for users in their org)* operationId: createRole tags: - Roles @@ -116,19 +131,17 @@ by_user_guid: summary: by user guid value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - user_group: - data: null + guid: 59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 05c5da3b-6cbc-421c-87c3-20bb3c41ab7c space: data: null links: @@ -141,19 +154,17 @@ by_username_and_origin: summary: by username and origin value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - user_group: - data: null + guid: 59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 05c5da3b-6cbc-421c-87c3-20bb3c41ab7c space: data: null links: @@ -198,7 +209,10 @@ /v3/roles/{guid}: get: summary: Get a role - description: This endpoint gets an individual role resource. + description: |- + This endpoint gets an individual role resource. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager *(Can see roles in managed organizations or spaces in those organizations)*, Org Auditor *(Can only see organization roles in audited organizations)*, Org Billing Manager *(Can only see organization roles in billing-managed organizations)*, Space Auditor *(Can see roles in audited spaces or parent organizations)*, Space Developer *(Can see roles in developed spaces or parent organizations)*, Space Manager *(Can see roles in managed spaces or parent organizations)*, Space Supporter *(Can see roles in supported spaces or parent organizations)* operationId: getRole tags: - Roles @@ -206,7 +220,7 @@ - $ref: ../components/parameters/Guid.yaml - name: include in: query - description: Optionally include additional related resources in the response; valid values are `user`, `space`, and `organization`. + description: Optionally include a list of unique related resources in the response; valid values are `user`, `space`, and `organization` schema: type: array items: @@ -226,19 +240,17 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 40557c70-d1bd-4976-a2ab-a85f5e882418 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: - guid: 123e4567-e89b-12d3-a456-426614174000 - user_group: - data: null + guid: 59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 05c5da3b-6cbc-421c-87c3-20bb3c41ab7c space: data: null links: @@ -272,7 +284,10 @@ $ref: ../components/responses/NotFound.yaml delete: summary: Delete a role - description: This endpoint deletes an individual role. + description: |- + This endpoint deletes an individual role. + + **Permitted roles:** Admin, Org Manager *(Can delete roles in managed organizations or spaces in those organizations)*, Space Manager *(Can delete roles in managed spaces)* operationId: deleteRole tags: - Roles diff --git a/docs/openapi/apis/cf/latest/paths/Root.yaml b/docs/openapi/apis/cf/latest/paths/Root.yaml index 43d47b2cfe5..93fac1b530d 100644 --- a/docs/openapi/apis/cf/latest/paths/Root.yaml +++ b/docs/openapi/apis/cf/latest/paths/Root.yaml @@ -2,9 +2,12 @@ get: summary: Global API Root description: |- This endpoint returns links to the APIs available on a given Cloud Foundry deployment. + + **Authentication:** No authentication required. operationId: getApiRoot tags: - Root + security: [] responses: '200': description: OK @@ -24,19 +27,36 @@ get: cloud_controller_v2: allOf: - $ref: '../components/schemas/IndexLink.yaml' - - description: Link to the Cloud Controller V2 API + - description: Link to the Cloud Controller V2 API; `meta.version` contains the V2 API version cloud_controller_v3: allOf: - $ref: '../components/schemas/IndexLink.yaml' - - description: Link to the Cloud Controller V3 API + - description: Link to the Cloud Controller V3 API; `meta.version` contains the V3 API version + network_policy_v0: + allOf: + - $ref: '../components/schemas/IndexLink.yaml' + - description: Link to the Network Policy V0 API network_policy_v1: allOf: - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Network Policy V1 API + login: + allOf: + - $ref: '../components/schemas/IndexLink.yaml' + - description: Link to the login server uaa: allOf: - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the UAA API + credhub: + oneOf: + - $ref: '../components/schemas/IndexLink.yaml' + - type: "null" + description: Link to the CredHub API; `null` when CredHub is not available + routing: + allOf: + - $ref: '../components/schemas/IndexLink.yaml' + - description: Link to the Routing API logging: allOf: - $ref: '../components/schemas/IndexLink.yaml' @@ -49,6 +69,47 @@ get: allOf: - $ref: '../components/schemas/IndexLink.yaml' - description: Link to the Log Stream API + app_ssh: + allOf: + - $ref: '../components/schemas/IndexLink.yaml' + - description: Link to the app SSH proxy; `meta.host_key_fingerprint` and `meta.oauth_client` describe the SSH endpoint + examples: + default: + summary: default + value: + links: + self: + href: https://api.example.org + cloud_controller_v2: + href: https://api.example.org/v2 + meta: + version: 2.155.0 + cloud_controller_v3: + href: https://api.example.org/v3 + meta: + version: 3.90.0 + network_policy_v0: + href: https://api.example.org/networking/v0/external + network_policy_v1: + href: https://api.example.org/networking/v1/external + login: + href: https://login.example.org + uaa: + href: https://uaa.example.org + credhub: null + routing: + href: https://api.example.org/routing + logging: + href: wss://doppler.example.org:443 + log_cache: + href: https://log-cache.example.org + log_stream: + href: https://log-stream.example.org + app_ssh: + href: ssh.example.org:2222 + meta: + host_key_fingerprint: Y411oivJwZCUQnXHq83mdM5SKCK4ftyoSXI31RRe4Zs + oauth_client: ssh-proxy '404': $ref: '../components/responses/NotFound.yaml' '500': 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 diff --git a/docs/openapi/apis/cf/latest/paths/Routes.yaml b/docs/openapi/apis/cf/latest/paths/Routes.yaml index a9bd493f22e..2437787eba5 100644 --- a/docs/openapi/apis/cf/latest/paths/Routes.yaml +++ b/docs/openapi/apis/cf/latest/paths/Routes.yaml @@ -1,83 +1,86 @@ /v3/routes: get: summary: List routes - description: Retrieve all routes the user has access to. + description: |- + Retrieve all routes the user has access to. + + **Permitted roles:** All Roles operationId: listRoutes tags: - Routes 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 - - name: protocols - in: query - schema: - type: array - items: - type: string - enum: - - http - - tcp - description: Comma-delimited list of protocols to filter by - name: hosts in: query schema: type: array items: type: string - description: Comma-delimited list of hosts to filter by + description: Comma-delimited list of hostnames to filter by - name: paths in: query schema: type: array items: type: string - description: Comma-delimited list of paths to filter by + description: Comma-delimited list of paths to filter by (e.g. `/path1,/path2`) - name: ports in: query schema: type: array items: type: integer - description: Comma-delimited list of ports to filter by + description: Comma-delimited list of ports to filter by (e.g. `3306,5432`) - name: domain_guids in: query schema: type: array items: type: string - description: Comma-delimited list of domain GUIDs to filter by + description: Comma-delimited list of domain guids to filter by - name: space_guids in: query schema: type: array items: type: string - description: Comma-delimited list of space GUIDs to filter by + description: Comma-delimited list of space guids to filter by - name: app_guids in: query schema: type: array items: type: string - description: Comma-delimited list of app GUIDs to filter by + description: Comma-delimited list of app guids to filter by - 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 - name: service_instance_guids in: query schema: type: array items: type: string - description: Comma-delimited list of service instance GUIDs to filter by + description: Comma-delimited list of service instance guids to filter by - name: include in: query schema: @@ -88,7 +91,8 @@ - domain - space.organization - space - description: Optionally include a list of unique related resources in the response + - route_policies + description: Optionally include a list of unique related resources in the response. Valid values are `domain`, `space.organization`, `space`, `route_policies` responses: '200': $ref: ../components/responses/RouteListResponse.yaml @@ -110,7 +114,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a route - description: Create a route. + description: |- + Create a route. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: createRoute tags: - Routes @@ -118,22 +125,7 @@ $ref: ../components/requestBodies/RouteCreateRequestBody.yaml responses: '201': - description: Route created - content: - application/json: - schema: - $ref: ../components/schemas/Route.yaml - links: - space: - operationId: getSpace - parameters: - guid: $response.body#/relationships/space/data/guid - description: Retrieve the space for this route - domain: - operationId: getDomain - parameters: - guid: $response.body#/relationships/domain/data/guid - description: Retrieve the domain for this route + $ref: ../components/responses/RouteCreateResponse.yaml '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -151,7 +143,10 @@ /v3/routes/{guid}: get: summary: Get a route - description: Retrieve a route. + description: |- + Retrieve a route. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getRoute tags: - Routes @@ -165,9 +160,10 @@ type: string enum: - domain - - space - space.organization - description: Optionally include a list of unique related resources in the response + - space + - route_policies + description: Optionally include additional related resources in the response. Valid values are `domain`, `space.organization`, `space`, `route_policies` responses: '200': description: Successfully retrieved route @@ -175,6 +171,60 @@ application/json: schema: $ref: ../components/schemas/Route.yaml + examples: + default: + summary: default + value: + guid: cbad697f-cac1-48f4-9017-ac08f39dfb31 + protocol: tcp + port: 6666 + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + host: a-hostname + path: /some_path + url: a-hostname.a-domain.com/some_path + destinations: + - guid: 385bf117-17f5-4689-8c5c-08c6cc821fed + app: + guid: 0a6636b5-7fc4-44d8-8752-0db3e40b35a5 + process: + type: web + weight: null + port: 8080 + protocol: tcp + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + - guid: 27e96a3b-5bcf-49ed-8048-351e0be23e6f + app: + guid: f61e59fa-2121-4217-8c7b-15bfd75baf25 + process: + type: web + weight: null + port: 8080 + protocol: tcp + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + options: + loadbalancing: round-robin + metadata: + labels: {} + annotations: {} + relationships: + space: + data: + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + data: + guid: 0b5f3633-194c-42d2-9408-972366617e0e + links: + self: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 + space: + href: https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + href: https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e + destinations: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations links: space: operationId: getSpace @@ -194,7 +244,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a route - description: Update a route. + description: |- + Update a route. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: updateRoute tags: - Routes @@ -208,9 +261,24 @@ schema: type: object properties: + options: + $ref: ../components/schemas/RouteOptions.yaml + description: Options applied to the route metadata: $ref: ../components/schemas/Metadata.yaml + description: Labels and annotations applied to the route description: Request schema for updating a route + examples: + default: + summary: default + value: + options: + loadbalancing: round-robin + metadata: + labels: + key: value + annotations: + note: detailed information responses: '200': description: Successfully updated route @@ -218,6 +286,60 @@ application/json: schema: $ref: ../components/schemas/Route.yaml + examples: + default: + summary: default + value: + guid: cbad697f-cac1-48f4-9017-ac08f39dfb31 + protocol: tcp + port: 6666 + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + host: a-hostname + path: "/some_path" + url: a-hostname.a-domain.com/some_path + destinations: + - guid: 385bf117-17f5-4689-8c5c-08c6cc821fed + app: + guid: 0a6636b5-7fc4-44d8-8752-0db3e40b35a5 + process: + type: web + weight: + port: 8080 + protocol: tcp + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + - guid: 27e96a3b-5bcf-49ed-8048-351e0be23e6f + app: + guid: f61e59fa-2121-4217-8c7b-15bfd75baf25 + process: + type: web + weight: + port: 8080 + protocol: tcp + created_at: '2019-05-10T17:17:48Z' + updated_at: '2019-05-10T17:17:48Z' + options: + loadbalancing: round-robin + metadata: + labels: {} + annotations: {} + relationships: + space: + data: + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + data: + guid: 0b5f3633-194c-42d2-9408-972366617e0e + links: + self: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 + space: + href: https://api.example.org/v3/spaces/885a8cb3-c07b-4856-b448-eeb10bf36236 + domain: + href: https://api.example.org/v3/domains/0b5f3633-194c-42d2-9408-972366617e0e + destinations: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/destinations links: space: operationId: getSpace @@ -247,7 +369,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a route - description: Delete a route. + description: |- + Delete a route. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: deleteRoute tags: - Routes @@ -275,15 +400,35 @@ /v3/apps/{guid}/routes: get: summary: List routes for an app - description: Retrieve all routes that have destinations that point to the given app. + description: |- + Retrieve all routes that have [destinations](#the-destination-object) that point to the given app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppRoutes tags: - Routes parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - $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/LabelSelector.yaml - name: domain_guids in: query schema: @@ -298,20 +443,34 @@ items: type: string description: Comma-delimited list of hostnames to filter by + - name: organization_guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of organization guids to filter by - name: paths in: query schema: type: array items: type: string - description: Comma-delimited list of paths to filter by + description: Comma-delimited list of paths to filter by (e.g. `/path1,/path2`) - name: ports in: query schema: type: array items: type: integer - description: Comma-delimited list of ports to filter by + description: Comma-delimited list of ports to filter by (e.g. `3306,5432`) + - name: space_guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of space guids to filter by responses: '200': description: OK @@ -327,14 +486,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org<%= path %>?page=1&per_page=2 + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=1&per_page=2 last: - href: https://api.example.org<%= path %>?page=2&per_page=2 + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2 next: - href: https://api.example.org<%= path %>?page=2&per_page=2 + href: https://api.example.org/v3/apps/1cb006ee-fb05-47e1-b541-c34179ddc446/routes?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: cbad697f-cac1-48f4-9017-ac08f39dfb31 protocol: http created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' @@ -342,9 +501,9 @@ path: /some_path url: a-hostname.a-domain.com/some_path destinations: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 385bf117-17f5-4689-8c5c-08c6cc821fed app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 0a6636b5-7fc4-44d8-8752-0db3e40b35a5 process: type: web weight: null @@ -352,9 +511,9 @@ protocol: http1 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 27e96a3b-5bcf-49ed-8048-351e0be23e6f app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: f61e59fa-2121-4217-8c7b-15bfd75baf25 process: type: web weight: null @@ -370,10 +529,10 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 domain: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 0b5f3633-194c-42d2-9408-972366617e0e links: self: href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31 @@ -391,8 +550,11 @@ $ref: ../components/responses/NotFound.yaml /v3/routes/{guid}/relationships/shared_spaces: get: - summary: List shared spaces relationship - description: Lists the spaces that the route has been shared to. + summary: Lists shared spaces relationship (experimental) + description: |- + Lists the spaces that the route has been shared to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listSharedSpacesRelationship tags: - Routes @@ -405,6 +567,16 @@ application/json: schema: $ref: ../components/schemas/RelationshipToMany.yaml + examples: + default: + summary: default + value: + data: + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f + links: + self: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/relationships/shared_spaces '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -413,14 +585,17 @@ $ref: ../components/responses/NotFound.yaml post: summary: Share a route with other spaces (experimental) - description: This endpoint shares the route with the specified spaces. This allows users with read and write access in both the route’s space and a shared space to bind a route to an app in the shared space. In order to share into a space the requesting user must have write permission in the target space. + description: |- + This endpoint shares the route with the specified spaces. This allows users with read and write access in both the route's space and a shared space to bind a route to an app in the shared space. In order to share into a space the requesting user must have write permission in the target space. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: shareRoute tags: - Routes parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: List of spaces to share the route with + description: Shared space relationships; each space will have this route shared to it required: true content: application/json: @@ -431,8 +606,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 responses: '200': description: OK @@ -440,6 +615,16 @@ application/json: schema: $ref: ../components/schemas/RelationshipToMany.yaml + examples: + default: + summary: default + value: + data: + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f + links: + self: + href: https://api.example.org/v3/routes/cbad697f-cac1-48f4-9017-ac08f39dfb31/relationships/shared_spaces '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -451,7 +636,10 @@ /v3/routes/{guid}/relationships/shared_spaces/{space_guid}: delete: summary: Unshare a route that was shared with another space (experimental) - description: Unshares a route that was shared with another space. + description: |- + Unshares a route that was shared with another space. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: unshareRoute tags: - Routes @@ -478,22 +666,59 @@ /v3/routes/{guid}/relationships/space: patch: summary: Transfer ownership (experimental) - description: Transfers a the ownership of a route to a another space. Users must have write access for both spaces to perform this action. The original owning space will still retain access to the route as a [shared space](#share-a-route-with-other-spaces-experimental). To completely remove a space from a route, users will have to use [unshare route](#unshare-a-route-that-was-shared-with-another-space-experimental). + description: |- + Transfers a the ownership of a route to a another space. Users must have write access for both spaces to perform this action. + The original owning space will still retain access to the route as a [shared space](#share-a-route-with-other-spaces-experimental). + To completely remove a space from a route, users will have to use [unshare route](#unshare-a-route-that-was-shared-with-another-space-experimental). + + **Permitted roles:** Admin, Space Developer operationId: transferRouteOwnership tags: - Routes parameters: - $ref: ../components/parameters/Guid.yaml requestBody: - description: The space to transfer ownership to + description: The space to transfer ownership of the route to required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToOne.yaml + type: object + properties: + data: + type: object + properties: + guid: + type: string + format: uuid + description: The GUID of the space to transfer ownership of the route to + required: + - guid + description: A relationship to the space that will own the route + required: + - data + examples: + default: + summary: default + value: + data: + guid: 885a8cb3-c07b-4856-b448-eeb10bf36236 responses: - '204': - description: No Content + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: string + description: Status of the ownership transfer + examples: + default: + summary: default + value: + status: ok '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -505,14 +730,29 @@ /v3/routes/{guid}/destinations: get: summary: List destinations for a route - description: Retrieve all destinations associated with a route. + description: |- + Retrieve all destinations associated with a route. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listDestinationsForRoute tags: - Routes parameters: - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml + - name: guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of destination guids to filter by + - name: app_guids + in: query + schema: + type: array + items: + type: string + description: Comma-delimited list of app guids to filter by responses: '200': description: List of destinations for the route @@ -525,9 +765,9 @@ summary: default value: destinations: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 89323d4e-2e84-43e7-83e9-adbf50a20c0e app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 process: type: web weight: null @@ -535,9 +775,9 @@ protocol: http2 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5 app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 01856e12-8ee8-11e9-98a5-bb397dbc818f process: type: api weight: null @@ -564,6 +804,8 @@ Add one or more destinations to a route, preserving any existing destinations. Weighted destinations (deprecated) cannot be added with this endpoint. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: insertDestinationsForRoute tags: - Routes @@ -583,9 +825,9 @@ summary: default value: destinations: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 89323d4e-2e84-43e7-83e9-adbf50a20c0e app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 process: type: web weight: null @@ -593,9 +835,9 @@ protocol: http2 created_at: '2019-05-10T17:17:48Z' updated_at: '2019-05-10T17:17:48Z' - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5 app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 01856e12-8ee8-11e9-98a5-bb397dbc818f process: type: api weight: null @@ -626,6 +868,8 @@ 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. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: replaceDestinationsForRouteWithPatch tags: - Routes @@ -645,17 +889,17 @@ summary: default value: destinations: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 89323d4e-2e84-43e7-83e9-adbf50a20c0e app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 process: type: web weight: 61 port: 8080 protocol: http2 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: fbef10a2-8ee7-11e9-aa2d-abeeaf7b83c5 app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 01856e12-8ee8-11e9-98a5-bb397dbc818f process: type: api weight: 39 @@ -679,7 +923,10 @@ /v3/routes/{guid}/destinations/{destination_guid}: patch: summary: Update a destination protocol for a route - description: This endpoint updates the protocol of a route destination (app, port and weight cannot be updated) + description: |- + This endpoint updates the protocol of a route destination (app, port and weight cannot be updated) + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: updateDestinationProtocolForRoute tags: - Routes @@ -701,13 +948,15 @@ type: object properties: protocol: - type: string - description: Protocol of the destination + type: + - string + - 'null' enum: - http1 - http2 - required: - - protocol + - tcp + - null + description: Protocol the destination will use. Valid protocols are `http1` or `http2` if route protocol is `http`, `tcp` if route protocol is `tcp`. A `null` value will set it to either `http1` or `tcp` based on the route protocol examples: default: summary: default @@ -724,9 +973,9 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 89323d4e-2e84-43e7-83e9-adbf50a20c0e app: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 process: type: web weight: 61 @@ -747,7 +996,10 @@ $ref: ../components/responses/UnprocessableEntity.yaml delete: summary: Remove destination for a route - description: Remove a destination from a route. + description: |- + Remove a destination from a route. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: removeDestinationForRoute tags: - Routes @@ -771,23 +1023,3 @@ $ref: ../components/responses/NotFound.yaml '422': $ref: ../components/responses/UnprocessableEntity.yaml -/v3/spaces/{guid}/routes: - delete: - summary: Delete unmapped routes for a space - description: Deletes all routes in a space that are not mapped to any applications and not bound to any service instances. - operationId: deleteUnmappedRoutesForSpace - tags: - - Routes - parameters: - - $ref: ../components/parameters/Guid.yaml - responses: - '204': - description: Successfully deleted unmapped routes from the space - '401': - $ref: ../components/responses/Unauthorized.yaml - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml - '422': - $ref: ../components/responses/UnprocessableEntity.yaml diff --git a/docs/openapi/apis/cf/latest/paths/SecurityGroups.yaml b/docs/openapi/apis/cf/latest/paths/SecurityGroups.yaml index a75141648a8..ba014bbde4f 100644 --- a/docs/openapi/apis/cf/latest/paths/SecurityGroups.yaml +++ b/docs/openapi/apis/cf/latest/paths/SecurityGroups.yaml @@ -1,42 +1,60 @@ /v3/security_groups: get: summary: List security groups - description: List security groups. + description: |- + Retrieve all security groups the user has access to. + + **Permitted roles:** Admin *(can see all security groups)*, Admin Read-Only *(can see all security groups)*, Global Auditor *(can see all security groups)*, Org Auditor *(can see globally–enabled security groups)*, Org Billing Manager *(can see globally–enabled security groups)*, Org Manager *(can see globally–enabled security groups or groups associated with a space they can see)*, Space Auditor *(can see globally–enabled security groups or groups associated with a space they can see)*, Space Developer *(can see globally–enabled security groups or groups associated with a space they can see)*, Space Manager *(can see globally–enabled security groups or groups associated with a space they can see)*, Space Supporter *(can see globally–enabled security groups or groups associated with a space they can see)* operationId: listSecurityGroups tags: - Security Groups 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 - name: guids in: query + required: false schema: type: array items: type: string - description: Comma-separated list of resource GUIDs to filter by + description: Comma-delimited list of security group guids to filter by - name: names in: query + required: false schema: type: array items: type: string - description: Comma-separated list of names to filter by (case insensitive) + description: Comma-delimited list of security group names to filter by (case-sensitive) - name: globally_enabled_running in: query + required: false schema: type: boolean description: If true, only include the security groups that are enabled for running - name: globally_enabled_staging in: query + required: false schema: type: boolean description: If true, only include the security groups that are enabled for staging - name: running_space_guids in: query + required: false schema: type: array items: @@ -44,6 +62,7 @@ description: Comma-delimited list of space guids to filter by - name: staging_space_guids in: query + required: false schema: type: array items: @@ -56,6 +75,62 @@ application/json: schema: $ref: ../components/schemas/SecurityGroupList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 1 + total_pages: 1 + first: + href: https://api.example.org/v3/security_groups?page=1&per_page=50 + last: + href: https://api.example.org/v3/security_groups?page=1&per_page=50 + next: null + previous: null + resources: + - guid: b85a788e-671f-4549-814d-e34cdb2f539a + created_at: '2020-02-20T17:42:08Z' + updated_at: '2020-02-20T17:42:08Z' + name: my-group0 + globally_enabled: + running: true + staging: false + rules: + - protocol: tcp + destination: 10.10.10.0/24 + ports: 443,80,8080 + - protocol: icmp + destination: 10.10.10.0/24 + type: 8 + code: 0 + description: Allow ping requests to private services + relationships: + staging_spaces: + data: + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 + running_spaces: + data: [] + links: + self: + href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a + - guid: a89a788e-671f-4549-814d-e34c1b2f533a + created_at: '2020-02-20T17:42:08Z' + updated_at: '2020-02-20T17:42:08Z' + name: my-group1 + globally_enabled: + running: true + staging: true + rules: [] + relationships: + staging_spaces: + data: [] + running_spaces: + data: [] + links: + self: + href: https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -74,11 +149,15 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a security group - description: Create a security group. + description: |- + Create a security group. + + **Permitted roles:** Admin operationId: createSecurityGroup tags: - Security Groups requestBody: + required: true content: application/json: schema: @@ -108,7 +187,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b85a788e-671f-4549-814d-e34cdb2f539a created_at: '2020-02-20T17:42:08Z' updated_at: '2020-02-20T17:42:08Z' name: my-group0 @@ -136,8 +215,8 @@ relationships: staging_spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 running_spaces: data: [] links: @@ -160,7 +239,10 @@ /v3/security_groups/{guid}: get: summary: Get a security group - description: Get a security group. + description: |- + Retrieve a security group. + + **Permitted roles:** Admin *(can see all security groups)*, Admin Read-Only *(can see all security groups)*, Global Auditor *(can see all security groups)*, Org Auditor *(can see globally enabled security groups)*, Org Billing Manager *(can see globally enabled security groups)*, Org Manager *(can see globally enabled security groups or groups associated with a space they can see)*, Space Auditor *(can see globally enabled security groups or groups associated with a space they can see)*, Space Developer *(can see globally enabled security groups or groups associated with a space they can see)*, Space Manager *(can see globally enabled security groups or groups associated with a space they can see)*, Space Supporter *(can see globally enabled security groups or groups associated with a space they can see)* operationId: getSecurityGroup tags: - Security Groups @@ -177,7 +259,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b85a788e-671f-4549-814d-e34cdb2f539a created_at: '2020-02-20T17:42:08Z' updated_at: '2020-02-20T17:42:08Z' name: my-group0 @@ -205,8 +287,8 @@ relationships: staging_spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 running_spaces: data: [] links: @@ -220,17 +302,41 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a security group - description: Update a security group. + description: |- + This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. + + Updates to the `rules` parameter will fully replace the current set of `rules` for the security group. + + Updates to the `globally_enabled` parameter will be merged with the existing configuration. For example, an update to the `globally_enabled.running` parameter will not affect the `globally_enabled.staging` configuration. + + **Permitted roles:** Admin operationId: updateSecurityGroup tags: - Security Groups parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + required: true content: application/json: schema: $ref: ../components/schemas/SecurityGroupUpdate.yaml + examples: + default: + summary: default + value: + name: my-group0 + globally_enabled: + running: true + rules: + - protocol: tcp + destination: 10.10.10.0/24 + ports: 443,80,8080 + - protocol: icmp + destination: 10.10.10.0/24 + type: 8 + code: 0 + description: Allow ping requests to private services responses: '200': description: OK @@ -242,7 +348,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b85a788e-671f-4549-814d-e34cdb2f539a created_at: '2020-02-20T17:42:08Z' updated_at: '2020-02-20T17:42:08Z' name: my-group0 @@ -270,8 +376,8 @@ relationships: staging_spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 running_spaces: data: [] links: @@ -295,7 +401,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a security group - description: Delete a security group. + description: |- + Delete a security group. + + **Permitted roles:** Admin operationId: deleteSecurityGroup tags: - Security Groups @@ -318,124 +427,45 @@ $ref: ../components/responses/NotFound.yaml '500': $ref: ../components/responses/500.yaml -/v3/spaces/{guid}/running_security_groups: - get: - summary: List running security groups for a space - description: This endpoint returns security groups that are enabled for running globally or at the space level for the given space. - operationId: listRunningSecurityGroupsForSpaceBySpaceGuid - tags: - - Security Groups - parameters: - - $ref: ../components/parameters/Guid.yaml - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: ../components/schemas/SecurityGroupList.yaml - '401': - $ref: ../components/responses/Unauthorized.yaml - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml -/v3/spaces/{guid}/staging_security_groups: - get: - summary: List staging security groups for a space - description: This endpoint returns security groups that are enabled for staging globally or at the space level for the given space. - operationId: listStagingSecurityGroupsForSpaceBySpaceGuid - tags: - - Security Groups - parameters: - - $ref: ../components/parameters/Guid.yaml - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: ../components/schemas/SecurityGroupList.yaml - '401': - $ref: ../components/responses/Unauthorized.yaml - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml - patch: - summary: Update a security group - description: This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. Updates to the `rules` parameter will fully replace the current set of `rules` for the security group. Updates to the `globally_enabled` parameter will be merged with the existing configuration. For example, an update to the `globally_enabled.running` parameter will not affect the `globally_enabled.staging` configuration. - operationId: updateSecurityGroup - tags: - - Security Groups - parameters: - - $ref: ../components/parameters/Guid.yaml - requestBody: - content: - application/json: - schema: - $ref: ../components/schemas/SecurityGroup.yaml - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: ../components/schemas/SecurityGroup.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 - delete: - summary: Delete a security group - description: Delete a security group. - operationId: deleteSecurityGroup - tags: - - Security Groups - parameters: - - $ref: ../components/parameters/Guid.yaml - responses: - '202': - description: Accepted - headers: - Location: - description: URL of the job that is deleting the security group - schema: - type: string - format: uri - '401': - $ref: ../components/responses/Unauthorized.yaml - '403': - $ref: ../components/responses/Forbidden.yaml - '404': - $ref: ../components/responses/NotFound.yaml - '422': - $ref: ../components/responses/UnprocessableEntity.yaml /v3/security_groups/{guid}/relationships/running_spaces: post: summary: Bind a running security group to spaces - description: This endpoint binds one or more spaces to a security group with the running lifecycle. Running app containers within these spaces will inherit the rules specified by this security group. Apps within these spaces must be restarted for these changes to take effect. Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it's visible, org and space managers can add it to additional spaces. + description: |- + This endpoint binds one or more spaces to a security group with the running lifecycle. + + Running app containers within these spaces will inherit the rules specified by this security group. + + Apps within these spaces must be restarted for these changes to take effect. + + Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it's visible, org and space managers can add it to additional spaces. + + **Permitted roles:** Admin, Space Manager *(can bind visible security groups to their spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)*, Org Manager *(can bind visible security groups to their organizations' spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)* operationId: bindRunningSecurityGroup tags: - Security Groups parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToMany.yaml + type: object + properties: + data: + type: array + items: + $ref: ../components/schemas/Relationship.yaml + description: Space guids that will be bound to the security group + required: + - data examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 responses: '200': description: OK @@ -443,6 +473,17 @@ application/json: schema: $ref: ../components/schemas/RelationshipToMany.yaml + examples: + default: + summary: default + value: + data: + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 + - guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + links: + self: + href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a/relationships/running_spaces '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -454,7 +495,12 @@ /v3/security_groups/{guid}/relationships/running_spaces/{space_guid}: delete: summary: Unbind a running security group from a space - description: This endpoint removes a space from a security group with the running lifecycle. Apps within this space must be restarted for these changes to take effect. + description: |- + This endpoint removes a space from a security group with the running lifecycle. + + Apps within this space must be restarted for these changes to take effect. + + **Permitted roles:** Admin, Space Manager *(can unbind visible security groups from their spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)*, Org Manager *(can unbind visible security groups from their organizations' spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)* operationId: unbindRunningSecurityGroup tags: - Security Groups @@ -475,24 +521,42 @@ /v3/security_groups/{guid}/relationships/staging_spaces: post: summary: Bind a staging security group to spaces - description: This endpoint binds one or more spaces to a security group with the staging lifecycle. Staging app containers within these spaces will inherit the rules specified by this security group. Apps within these spaces must be restaged for these changes to take effect. Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it's visible, org and space managers can add it to additional spaces. + description: |- + This endpoint binds one or more spaces to a security group with the staging lifecycle. + + Staging app containers within these spaces will inherit the rules specified by this security group. + + Apps within these spaces must be restaged for these changes to take effect. + + Unless a security group is globally-enabled, an admin must add it to a space for it to be visible for the org and space managers. Once it's visible, org and space managers can add it to additional spaces. + + **Permitted roles:** Admin, Space Manager *(can bind visible security groups to their spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)*, Org Manager *(can bind visible security groups to their organizations' spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)* operationId: bindStagingSecurityGroup tags: - Security Groups parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToMany.yaml + type: object + properties: + data: + type: array + items: + $ref: ../components/schemas/Relationship.yaml + description: Space guids that will be bound to the security group + required: + - data examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 responses: '200': description: OK @@ -500,6 +564,17 @@ application/json: schema: $ref: ../components/schemas/RelationshipToMany.yaml + examples: + default: + summary: default + value: + data: + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 + - guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + links: + self: + href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a/relationships/staging_spaces '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -511,7 +586,12 @@ /v3/security_groups/{guid}/relationships/staging_spaces/{space_guid}: delete: summary: Unbind a staging security group from a space - description: This endpoint removes a space from a security group with the staging lifecycle. Apps within this space must be restaged for these changes to take effect. + description: |- + This endpoint removes a space from a security group with the staging lifecycle. + + Apps within this space must be restaged for these changes to take effect. + + **Permitted roles:** Admin, Space Manager *(can unbind visible security groups from their spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)*, Org Manager *(can unbind visible security groups from their organizations' spaces; visible groups are globally–enabled security groups or groups associated with a space they can see)* operationId: unbindStagingSecurityGroup tags: - Security Groups diff --git a/docs/openapi/apis/cf/latest/paths/ServiceBrokers.yaml b/docs/openapi/apis/cf/latest/paths/ServiceBrokers.yaml index f4eb40f672b..add4cc01155 100644 --- a/docs/openapi/apis/cf/latest/paths/ServiceBrokers.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServiceBrokers.yaml @@ -1,28 +1,45 @@ /v3/service_brokers: get: summary: List service brokers - description: This endpoint retrieves the service brokers the user has access to. + description: |- + This endpoint retrieves the service brokers the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Space Developer *(only space-scoped brokers)*, Space Supporter *(only space-scoped brokers)*, Other *(will receive an empty list)* operationId: listServiceBrokers tags: - Service Brokers parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service broker names to filter by + description: Comma-delimited list of service broker names to filter by (case-sensitive) + - $ref: ../components/parameters/Page.yaml + - $ref: ../components/parameters/PerPage.yaml - name: space_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of space guids to filter by + description: Comma-delimited list of space GUIDs to filter by + - 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`, `name` - $ref: ../components/parameters/LabelSelector.yaml - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml @@ -41,14 +58,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/service_brokers?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/service_brokers?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/service_brokers?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 name: my_service_broker url: https://example.service-broker.com created_at: '2015-11-13T17:02:56Z' @@ -62,7 +79,7 @@ href: https://api.example.org/v3/service_brokers/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_offerings: href: https://api.example.org/v3/service_offerings?service_broker_guids=dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62 name: another_service_broker url: https://another-example.service-broker.com created_at: '2015-11-13T17:02:56Z' @@ -70,7 +87,7 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 metadata: labels: {} annotations: {} @@ -99,7 +116,11 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a service broker - description: This endpoint creates a new service broker and a job to synchronize the service offerings and service plans with those in the broker’s catalog. The `Location` header refers to the created job which syncs the broker with the catalog. See [_Service broker jobs_](#service-broker-jobs) for more information and limitations. + description: |- + This endpoint creates a new service broker and a job to synchronize the service offerings and service plans with those in the broker's catalog. + The `Location` header refers to the created job which syncs the broker with the catalog. See [_Service broker jobs_](#service-broker-jobs) for more information and limitations. + + **Permitted roles:** Admin, Space Developer *(Space Developers can only create space-scoped brokers; space-scoped brokers can only be created when the `space_scoped_private_broker_creation` feature flag is `true`)* operationId: createServiceBroker tags: - Service Brokers @@ -110,7 +131,7 @@ description: Accepted headers: Location: - description: URL of the job that is creating the service broker + description: URL of the job that is creating the service broker and synchronizing its catalog schema: type: string format: uri @@ -131,12 +152,16 @@ /v3/service_brokers/{guid}: get: summary: Get a service broker - description: This endpoint retrieves the service broker by GUID. + description: |- + This endpoint retrieves the service broker by GUID. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Space Developer *(only space-scoped brokers)*, Space Supporter *(only space-scoped brokers)* operationId: getServiceBroker tags: - Service Brokers parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service broker responses: '200': description: OK @@ -148,7 +173,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 name: my_service_broker url: https://example.service-broker.com created_at: '2015-11-13T17:02:56Z' @@ -156,7 +181,7 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 metadata: labels: type: dev @@ -183,19 +208,30 @@ patch: summary: Update a service broker description: |- - This endpoint updates a service broker. Depending on the parameters specified, the endpoint may respond with a background job, and it may synchronize the service offerings and service plans with those in the broker’s catalog. + This endpoint updates a service broker. Depending on the parameters specified, the endpoint may respond with a background job, and it may synchronize the service offerings and service plans with those in the broker's catalog. When a service broker has a synchronization job in progress, only updates with `metadata` are permitted until the synchronization job is complete. + + Parameter | Updates Catalog | Responds with job + --------- | --------------- | ----------------- + **name** | No | Yes + **url** | Yes | Yes + **authentication** | Yes | Yes + **metadata.labels** | No | No + **metadata.annotations** | No | No + + **Permitted roles:** Admin, Space Developer *(only space-scoped brokers)* operationId: updateServiceBroker tags: - Service Brokers parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service broker requestBody: $ref: ../components/requestBodies/ServiceBrokerUpdateRequestBody.yaml responses: '200': - description: OK + description: OK; returned when the update did not require a synchronization job content: application/json: schema: @@ -204,7 +240,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 name: my_service_broker url: https://example.service-broker.com created_at: '2015-11-13T17:02:56Z' @@ -212,7 +248,7 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 metadata: labels: type: dev @@ -231,7 +267,7 @@ guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service broker (space-scoped brokers only) '202': - description: Accepted + description: Accepted; returned when the update requires a synchronization job headers: Location: description: URL of the job that is updating the service broker @@ -256,12 +292,16 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a service broker - description: This endpoint creates a job to delete an existing service broker. The `Location` header refers to the created job. See [_Service broker jobs_](#service-broker-jobs) for more information and limitations. + description: |- + This endpoint creates a job to delete an existing service broker. The `Location` header refers to the created job. See [_Service broker jobs_](#service-broker-jobs) for more information and limitations. + + **Permitted roles:** Admin, Space Developer *(only space-scoped brokers)* operationId: deleteServiceBroker tags: - Service Brokers parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service broker responses: '202': description: Accepted diff --git a/docs/openapi/apis/cf/latest/paths/ServiceCredentialBindings.yaml b/docs/openapi/apis/cf/latest/paths/ServiceCredentialBindings.yaml index 4542b906b8c..fb70eeae3ce 100644 --- a/docs/openapi/apis/cf/latest/paths/ServiceCredentialBindings.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServiceCredentialBindings.yaml @@ -1,62 +1,57 @@ /v3/service_credential_bindings: get: summary: List service credential bindings - description: This endpoint retrieves the service credential bindings the user has access to. + description: |- + This endpoint retrieves the service credential bindings the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listServiceCredentialBindings tags: - Service Credential Bindings parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - - $ref: ../components/parameters/LabelSelector.yaml - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service credential binding names to filter by + description: Comma-delimited list of service credential binding names to filter by (case-sensitive) - name: service_instance_guids in: query + required: false schema: type: array items: type: string description: Comma-delimited list of service instance guids to filter by - - name: app_guids + - name: service_instance_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app guids to filter by - - name: type - in: query - schema: - type: string - enum: - - app - - key - description: Type of credential binding to filter by. Valid values are 'app' or 'key' - - name: service_instance_names + description: Comma-delimited list of service instance names to filter by (case-sensitive) + - name: app_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service instance names to filter by + description: Comma-delimited list of app guids to filter by - name: app_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of app names to filter by + description: Comma-delimited list of app names to filter by (case-insensitive) - name: service_plan_guids in: query + required: false schema: type: array items: @@ -64,13 +59,15 @@ description: Comma-delimited list of service plan guids to filter by - name: service_plan_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service plan names to filter by + description: Comma-delimited list of service plan names to filter by (case-insensitive) - name: service_offering_guids in: query + required: false schema: type: array items: @@ -78,20 +75,34 @@ description: Comma-delimited list of service offering guids to filter by - name: service_offering_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service offering names to filter by + description: Comma-delimited list of service offering names to filter by (case-insensitive) + - name: type + in: query + required: false + schema: + type: string + enum: + - app + - key + description: 'Type of credential binding to filter by. Valid values are: `app` or `key`' - name: guids in: query + required: false schema: type: array items: type: string description: Comma-delimited list of service credential binding guids to filter by + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml - name: include in: query + required: false schema: type: array items: @@ -100,13 +111,100 @@ - app - service_instance description: 'Optionally include a list of unique related resources in the response. Valid values are: `app`, `service_instance`' + - $ref: ../components/parameters/LabelSelector.yaml + - $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 + description: Request succeeded content: application/json: schema: $ref: ../components/schemas/ServiceCredentialBindingList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/service_credential_bindings?page=1&per_page=2 + last: + href: https://api.example.org/v3/service_credential_bindings?page=2&per_page=2 + next: + href: https://api.example.org/v3/service_credential_bindings?page=2&per_page=2 + previous: null + resources: + - guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + name: some-binding-name + type: app + last_operation: + type: create + state: succeeded + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + metadata: + annotations: + foo: bar + labels: + baz: qux + relationships: + app: + data: + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 + service_instance: + data: + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e + links: + self: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 + details: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details + service_instance: + href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e + app: + href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fdd555b8f13 + - guid: 7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62 + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + name: some-key-name + type: key + last_operation: + type: create + state: succeeded + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + metadata: + annotations: + foo: bar + labels: {} + relationships: + service_instance: + data: + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e + links: + self: + href: https://api.example.org/v3/service_credential_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62 + details: + href: https://api.example.org/v3/service_credential_bindings/7aa37bad-6ccb-4ef9-ba48-9ce3a91b2b62/details + service_instance: + href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -126,9 +224,13 @@ post: summary: Create a service credential binding description: |- - This endpoint creates a new service credential binding. Service credential bindings can be of type `app` or `key`; `key` is only valid for managed service instances. + This endpoint creates a new service credential binding. Service credential bindings can be of type `app` or `key`; `key` is only + valid for managed service instances. - If failures occur when creating a service credential binding for a managed service instances, the API might execute orphan mitigation steps accordingly to cases outlined in the [OSBAPI specification](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) + If failures occur when creating a service credential binding for a managed service instances, the API might execute orphan mitigation steps + accordingly to cases outlined in the [OSBAPI specification](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) + + **Permitted roles:** Admin, Space Developer, Space Supporter *(Only allowed to create bindings of type `app`.)* operationId: createServiceCredentialBinding tags: - Service Credential Bindings @@ -136,23 +238,16 @@ $ref: ../components/requestBodies/ServiceCredentialBindingCreateRequestBody.yaml responses: '201': - description: Created + description: User-provided service instance credential binding created content: application/json: schema: - oneOf: - - $ref: ../components/schemas/AppCredentialBinding.yaml - - $ref: ../components/schemas/KeyCredentialBinding.yaml - discriminator: - propertyName: type - mapping: - app: ../components/schemas/AppCredentialBinding.yaml - key: ../components/schemas/KeyCredentialBinding.yaml + $ref: ../components/schemas/AppCredentialBinding.yaml examples: - default: - summary: default + app_credential_binding: + summary: App credential binding value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' name: some-name @@ -170,10 +265,10 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 service_instance: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e links: self: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 @@ -184,15 +279,17 @@ service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e app: - href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13 + href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fdd555b8f13 '202': - description: Accepted + description: Managed service instance credential binding creation accepted; the binding is being created asynchronously headers: Location: - description: URL of the job that is creating the service credential binding + description: URL of the [job](#jobs) that is creating the service credential binding schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -210,7 +307,10 @@ /v3/service_credential_bindings/{guid}: get: summary: Get a service credential binding - description: This endpoint retrieves the service credential binding by GUID. + description: |- + This endpoint retrieves the service credential binding by GUID. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getServiceCredentialBinding tags: - Service Credential Bindings @@ -218,6 +318,7 @@ - $ref: ../components/parameters/Guid.yaml - name: include in: query + required: false schema: type: array items: @@ -225,10 +326,10 @@ enum: - app - service_instance - description: Optionally include a list of unique related resources in the response + description: 'Optionally include a list of unique related resources in the response. Valid values are: `app`, `service_instance`' responses: '200': - description: OK + description: Request succeeded content: application/json: schema: @@ -240,6 +341,74 @@ mapping: app: ../components/schemas/AppCredentialBinding.yaml key: ../components/schemas/KeyCredentialBinding.yaml + examples: + app_credential_binding: + summary: App credential binding + value: + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + name: some-name + type: app + last_operation: + type: create + state: succeeded + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + metadata: + annotations: + foo: bar + labels: + baz: qux + relationships: + app: + data: + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 + service_instance: + data: + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e + links: + self: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 + details: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details + parameters: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters + service_instance: + href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e + app: + href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fdd555b8f13 + key_credential_binding: + summary: Key credential binding + value: + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + name: some-name + type: key + last_operation: + type: create + state: succeeded + created_at: '2015-11-13T17:02:56Z' + updated_at: '2016-06-08T16:41:26Z' + metadata: + annotations: + foo: bar + labels: + baz: qux + relationships: + service_instance: + data: + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e + links: + self: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 + details: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/details + parameters: + href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters + service_instance: + href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e links: app: operationId: getApp @@ -259,7 +428,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a service credential binding - description: This endpoint updates a service credential binding with labels and annotations. + description: |- + This endpoint updates a service credential binding with labels and annotations. + + **Permitted roles:** Admin, Space Developer operationId: updateServiceCredentialBinding tags: - Service Credential Bindings @@ -269,7 +441,7 @@ $ref: ../components/requestBodies/ServiceCredentialBindingUpdateRequestBody.yaml responses: '200': - description: OK + description: Request succeeded content: application/json: schema: @@ -285,7 +457,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' name: some-name @@ -303,10 +475,10 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 service_instance: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e links: self: href: https://api.example.org/v3/service_credential_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 @@ -317,7 +489,7 @@ service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e app: - href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fddss5b8f13 + href: https://api.example.org/v3/apps/74f7c078-0934-470f-9883-4fdd555b8f13 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -336,7 +508,12 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a service credential binding - description: This endpoint deletes a service credential binding. When deleting credential bindings originated from user provided service instances, the delete operation does not require interactions with service brokers, therefore the API will respond synchronously to the delete request. + description: |- + This endpoint deletes a service credential binding. When deleting credential bindings originated from user provided + service instances, the delete operation does not require interactions with service brokers, therefore the API will + respond synchronously to the delete request. + + **Permitted roles:** Admin, Space Developer, Space Supporter *(Only allowed to delete bindings of type `app`.)* operationId: deleteServiceCredentialBinding tags: - Service Credential Bindings @@ -344,15 +521,17 @@ - $ref: ../components/parameters/Guid.yaml responses: '202': - description: Accepted + description: Managed service instance credential binding deletion accepted; the binding is being deleted asynchronously headers: Location: - description: URL of the job that is deleting the service credential binding + description: URL of the [job](#jobs) that is deleting the service credential binding schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '204': - description: No Content + description: User-provided service instance credential binding deleted '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -366,7 +545,10 @@ /v3/service_credential_bindings/{guid}/details: get: summary: Get a service credential binding details - description: This endpoint retrieves the service credential binding details. + description: |- + This endpoint retrieves the service credential binding details. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer operationId: getServiceCredentialBindingDetails tags: - Service Credential Bindings @@ -374,11 +556,21 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: Request succeeded content: application/json: schema: - type: object + $ref: ../components/schemas/ServiceCredentialBindingDetails.yaml + examples: + default: + summary: default + value: + credentials: + connection: mydb://user@password:example.com + syslog_drain_url: http://syslog.example.com/drain + volume_mounts: + - /vcap/data + - store '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -388,7 +580,13 @@ /v3/service_credential_bindings/{guid}/parameters: get: summary: Get parameters for a service credential binding - description: Queries the Service Broker for the parameters associated with this service credential binding. The broker catalog must have enabled the `bindings_retrievable` feature for the Service Offering. Check the [Service Offering object](#the-service-offering-object) for the value of this feature flag. This endpoint is not available for User-Provided Service Instances. + description: |- + Queries the Service Broker for the parameters associated with this service credential binding. + The broker catalog must have enabled the `bindings_retrievable` feature for the Service Offering. + Check the [Service Offering object](#the-service-offering-object) for the value of this feature flag. + This endpoint is not available for User-Provided Service Instances. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer, Space Supporter operationId: getServiceCredentialBindingParameters tags: - Service Credential Bindings @@ -396,17 +594,21 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: Request succeeded content: application/json: schema: type: object + additionalProperties: true + description: The parameters that the service credential binding was created with, as returned by the service broker examples: default: summary: default value: foo: bar foz: baz + '400': + $ref: ../components/responses/BadRequest.yaml '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/ServiceInstances.yaml b/docs/openapi/apis/cf/latest/paths/ServiceInstances.yaml index ecdb77c9836..448b563b418 100644 --- a/docs/openapi/apis/cf/latest/paths/ServiceInstances.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServiceInstances.yaml @@ -1,20 +1,25 @@ /v3/service_instances: get: summary: List service instances - description: This endpoint retrieves the service instances the user has access to, including access granted by service instance sharing. + description: |- + This endpoint retrieves the service instances the user has access to, including access granted by service instance sharing. + + **Permitted roles:** All Roles operationId: listServiceInstances tags: - Service Instances parameters: - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service instance names to filter by + description: Comma-delimited list of service instance names to filter by (case-sensitive) - name: guids in: query + required: false schema: type: array items: @@ -22,14 +27,16 @@ description: Comma-delimited list of service instance guids to filter by - name: type in: query + required: false schema: type: string enum: - managed - user-provided - description: Filter by type; valid values are 'managed' and 'user-provided' + description: Filter by type; valid values are `managed` and `user-provided` - name: space_guids in: query + required: false schema: type: array items: @@ -37,6 +44,7 @@ description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false schema: type: array items: @@ -44,6 +52,7 @@ description: Comma-delimited list of organization guids to filter by - name: service_plan_guids in: query + required: false schema: type: array items: @@ -51,22 +60,65 @@ description: Comma-delimited list of service plan guids to filter by - name: service_plan_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service plan names to filter by + description: Comma-delimited list of service plan names to filter by (case-insensitive) - $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/LabelSelector.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - name: fields in: query + required: false + style: deepObject + explode: true schema: type: object - description: Fields to include in the response + properties: + space: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name`, `relationships.organization` + space.organization: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + service_plan: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name`, `relationships.service_offering` + service_plan.service_offering: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name`, `description`, `documentation_url`, `tags`, `relationships.service_broker` + service_plan.service_offering.service_broker: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Service instances list fields: + + Resource | Allowed Keys + --- | --- + `space` | `guid`, `name`, `relationships.organization` + `space.organization` | `guid`, `name` + `service_plan` | `guid`, `name`, `relationships.service_offering` + `service_plan.service_offering` | `guid`, `name`, `description`, `documentation_url`, `tags`, `relationships.service_broker` + `service_plan.service_offering.service_broker` | `guid`, `name` + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml responses: '200': description: Request succeeded @@ -88,14 +140,14 @@ next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: c89b3280-fe8d-4aa0-a42e-44465bb1c61c created_at: '2020-03-10T15:49:29Z' updated_at: '2020-03-10T15:49:29Z' name: my-managed-instance tags: [] type: managed maintenance_info: - version: 1.0.0 + version: '1.0.0' upgrade_available: false dashboard_url: https://service-broker.example.org/dashboard broker_provided_metadata: @@ -112,10 +164,10 @@ relationships: service_plan: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 5358d122-638e-11ea-afca-bf6e756684ac space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 metadata: labels: {} annotations: {} @@ -134,7 +186,7 @@ href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c service_route_bindings: href: https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 88ce23e5-27c3-4381-a2df-32a28ec43133 created_at: '2020-03-10T15:56:08Z' updated_at: '2020-03-10T15:56:08Z' name: my-user-provided-instance @@ -152,7 +204,7 @@ relationships: space: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 metadata: labels: {} annotations: {} @@ -186,9 +238,14 @@ post: summary: Create a service instance description: |- - This endpoint creates a new service instance. Service instances can be of type `managed` or `user-provided`, and the required parameters are different for each type. User provided service instances do not require interactions with service brokers. + This endpoint creates a new service instance. Service instances can be of type `managed` or `user-provided`, and + the required parameters are different for each type. User provided service instances do not require interactions with + service brokers. - If failures occur when creating managed service instances, the API might execute orphan mitigation steps accordingly to cases outlined in the [OSBAPI specification](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) + If failures occur when creating managed service instances, the API might execute orphan mitigation steps + accordingly to cases outlined in the [OSBAPI specification](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md#orphan-mitigation) + + **Permitted roles:** Admin, Space Developer operationId: createServiceInstance tags: - Service Instances @@ -196,11 +253,50 @@ $ref: ../components/requestBodies/ServiceInstanceCreateRequestBody.yaml responses: '201': - description: User Provided Service instance created + description: User-provided service instance created content: application/json: schema: $ref: ../components/schemas/UserProvidedServiceInstance.yaml + examples: + user_provided_service_instance: + summary: User-provided service instance + value: + guid: 88ce23e5-27c3-4381-a2df-32a28ec43133 + created_at: '2020-03-10T15:56:08Z' + updated_at: '2020-03-10T15:56:08Z' + last_operation: + type: create + state: succeeded + description: Operation succeeded + updated_at: '2020-03-10T15:49:32Z' + created_at: '2020-03-10T15:49:29Z' + name: my-user-provided-instance + tags: + - sql + type: user-provided + syslog_drain_url: http://logs.com + route_service_url: https://routes.com + relationships: + space: + data: + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + metadata: + labels: + baz: qux + annotations: + foo: bar + links: + self: + href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133 + space: + href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 + credentials: + href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials + service_credential_bindings: + href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 + service_route_bindings: + href: https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 links: space: operationId: getSpace @@ -208,13 +304,15 @@ guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this service instance '202': - description: Service instance creation in progress + description: Managed service instance creation accepted; the instance is being created asynchronously headers: Location: - description: URL of the job that is creating the service instance + description: URL of the [job](#jobs) that is creating the service instance schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -232,7 +330,11 @@ /v3/service_instances/{guid}/credentials: get: summary: Get credentials for a user-provided service instance - description: Retrieves the credentials for a user-provided service instance. This endpoint is not available for managed service instances. + description: |- + Retrieves the credentials for a user-provided service instance. + This endpoint is not available for managed service instances. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer, Space Manager operationId: getServiceInstanceCredentials tags: - Service Instances @@ -240,11 +342,12 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: The credentials of the user-provided service instance content: application/json: schema: type: object + description: The JSON object that was supplied as the `credentials` of the user-provided service instance examples: default: summary: default @@ -261,7 +364,10 @@ /v3/service_instances/{guid}/relationships/shared_spaces/usage_summary: get: summary: Get usage summary in shared spaces - description: This endpoint returns the number of bound apps in spaces where the service instance has been shared to. + description: |- + This endpoint returns the number of bound apps in spaces where the service instance has been shared to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getServiceInstanceUsageSummaryInSharedSpaces tags: - Service Instances @@ -269,7 +375,7 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: The usage summary for each space the service instance is shared to content: application/json: schema: @@ -282,18 +388,34 @@ properties: space: $ref: ../components/schemas/Relationship.yaml + description: The space the service instance has been shared to bound_app_count: type: integer + description: The number of apps bound to the service instance in that space + description: One entry for each space the service instance has been shared to + links: + type: object + properties: + self: + $ref: ../components/schemas/Link.yaml + description: Link to this usage summary + shared_spaces: + $ref: ../components/schemas/Link.yaml + description: Link to the spaces this service instance has been shared to + service_instance: + $ref: ../components/schemas/Link.yaml + description: Link to the service instance + description: Links to related resources examples: default: summary: default value: usage_summary: - space: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac bound_app_count: 2 - space: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c bound_app_count: 0 links: self: @@ -311,7 +433,10 @@ /v3/service_instances/{guid}/relationships/shared_spaces: get: summary: List shared spaces relationship - description: This endpoint lists the spaces that the service instance has been shared to. + description: |- + This endpoint lists the spaces that the service instance has been shared to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listServiceInstanceSharedSpaces tags: - Service Instances @@ -319,12 +444,30 @@ - $ref: ../components/parameters/Guid.yaml - name: fields in: query + required: false + style: deepObject + explode: true schema: type: object - description: Fields to include in the response + properties: + space: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name`, `relationships.organization` + space.organization: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Shared spaces list fields: + + Resource | Allowed Keys + --- | --- + `space` | `guid`, `name`, `relationships.organization` + `space.organization` | `guid`, `name` responses: '200': - description: OK + description: The spaces the service instance has been shared to content: application/json: schema: @@ -334,8 +477,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/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces @@ -347,27 +490,41 @@ $ref: ../components/responses/NotFound.yaml post: summary: Share a service instance to other spaces - description: This endpoint shares the service instance with the specified spaces. In order to share into a space the requesting user must be a space developer in the target space. + description: |- + This endpoint shares the service instance with the specified spaces. + In order to share into a space the requesting user must be a space developer in the target space. + + **Permitted roles:** Admin, Space Developer operationId: shareServiceInstance tags: - Service Instances parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: The spaces to share this service instance to + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToMany.yaml + type: object + required: + - data + properties: + data: + type: array + items: + $ref: ../components/schemas/Relationship.yaml + description: Shared space relationships; each space will have this service instance shared to it 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 + description: The spaces the service instance has been shared to content: application/json: schema: @@ -377,8 +534,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/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces @@ -393,7 +550,11 @@ /v3/service_instances/{guid}/relationships/shared_spaces/{space_guid}: delete: summary: Unshare a service instance from another space - description: This endpoint unshares the service instance from the specified space. This will automatically unbind any applications bound to this service instance in the specified space. Unsharing a service instance from a space will not delete any service keys. + description: |- + This endpoint unshares the service instance from the specified space. This will automatically unbind any applications bound to this service instance in the specified space. + Unsharing a service instance from a space will not delete any service keys. + + **Permitted roles:** Admin, Space Developer operationId: unshareServiceInstance tags: - Service Instances @@ -405,9 +566,10 @@ schema: type: string format: uuid + description: The GUID of the space to unshare the service instance from responses: '204': - description: No Content + description: Service instance unshared from the space '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -421,7 +583,12 @@ /v3/service_instances/{guid}/parameters: get: summary: Get parameters for a managed service instance - description: Queries the Service Broker for the parameters associated with this service instance. The broker catalog must have enabled the `instances_retrievable` feature for the Service Offering. Check the [Service Offering object](#the-service-offering-object) for the value of this feature flag. + description: |- + Queries the Service Broker for the parameters associated with this service instance. + The broker catalog must have enabled the `instances_retrievable` feature for the Service Offering. + Check the [Service Offering object](#the-service-offering-object) for the value of this feature flag. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager operationId: getServiceInstanceParameters tags: - Service Instances @@ -429,11 +596,12 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: The parameters the service instance was created or updated with content: application/json: schema: type: object + description: The JSON object of parameters returned by the service broker examples: default: summary: default @@ -450,9 +618,11 @@ get: summary: Get permissions for a service instance description: |- - Get the current user’s permissions for the given service instance. If a user can get a service instance then they can ‘read’ it. Users who can update a service instance can ‘manage’ it. + Get the current user's permissions for the given service instance. If a user can get a service instance then they can 'read' it. Users who can update a service instance can 'manage' it. + + This endpoint's primary purpose is to enable third-party service dashboards to determine the permissions of a given Cloud Foundry user that has authenticated with the dashboard via single sign-on (SSO). For more information, see the Cloud Foundry documentation on [Dashboard Single Sign-On](https://docs.cloudfoundry.org/services/dashboard-sso.html). - This endpoint’s primary purpose is to enable third-party service dashboards to determine the permissions of a given Cloud Foundry user that has authenticated with the dashboard via single sign-on (SSO). For more information, see the Cloud Foundry documentation on [Dashboard Single Sign-On](https://docs.cloudfoundry.org/services/dashboard-sso.html). + **Permitted roles:** All Roles operationId: getServiceInstancePermissions tags: - Service Instances @@ -460,7 +630,7 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: The current user's permissions for the service instance content: application/json: schema: @@ -468,8 +638,10 @@ properties: read: type: boolean + description: Whether the current user can read the service instance manage: type: boolean + description: Whether the current user can update the service instance examples: default: summary: default @@ -485,7 +657,10 @@ /v3/service_instances/{guid}: get: summary: Get a service instance - description: This endpoint retrieves the service instance by GUID. + description: |- + This endpoint retrieves the service instance by GUID. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getServiceInstance tags: - Service Instances @@ -493,12 +668,42 @@ - $ref: ../components/parameters/Guid.yaml - name: fields in: query + required: false + style: deepObject + explode: true schema: type: object - description: Fields to include in the response + properties: + space: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + space.organization: + type: string + description: Comma-delimited list of keys; valid values are `name`, `guid` + service_plan: + type: string + description: Comma-delimited list of keys; valid values are `name`, `guid` + service_plan.service_offering: + type: string + description: Comma-delimited list of keys; valid values are `name`, `guid`, `description`, `documentation_url`, `tags` + service_plan.service_offering.service_broker: + type: string + description: Comma-delimited list of keys; valid values are `name`, `guid` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Service instance fields: + + Resource | Allowed Keys + --- | --- + `space` | `guid`, `name` + `space.organization` | `name`, `guid` + `service_plan` | `name`, `guid` + `service_plan.service_offering` | `name`, `guid`, `description`, `documentation_url`, `tags` + `service_plan.service_offering.service_broker` | `name`, `guid` responses: '200': - description: OK + description: The requested service instance content: application/json: schema: @@ -510,6 +715,92 @@ mapping: managed: ../components/schemas/ManagedServiceInstance.yaml user-provided: ../components/schemas/UserProvidedServiceInstance.yaml + examples: + managed_service_instance: + summary: Managed service instance + value: + guid: c89b3280-fe8d-4aa0-a42e-44465bb1c61c + created_at: '2020-03-10T15:49:29Z' + updated_at: '2020-03-10T15:49:29Z' + name: my-managed-instance + tags: [] + type: managed + maintenance_info: + version: '1.0.0' + upgrade_available: false + dashboard_url: https://service-broker.example.org/dashboard + broker_provided_metadata: + labels: + service_engine_version: '16.6' + attributes: + max_connections: '100' + last_operation: + type: create + state: succeeded + description: Operation succeeded + updated_at: '2020-03-10T15:49:32Z' + created_at: '2020-03-10T15:49:29Z' + relationships: + service_plan: + data: + guid: 5358d122-638e-11ea-afca-bf6e756684ac + space: + data: + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c + service_plan: + href: https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac + space: + href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 + parameters: + href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters + shared_spaces: + href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces + service_credential_bindings: + href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c + service_route_bindings: + href: https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c + user_provided_service_instance: + summary: User-provided service instance + value: + guid: 88ce23e5-27c3-4381-a2df-32a28ec43133 + created_at: '2020-03-10T15:56:08Z' + updated_at: '2020-03-10T15:56:08Z' + last_operation: + type: create + state: succeeded + description: Operation succeeded + updated_at: '2020-03-10T15:49:32Z' + created_at: '2020-03-10T15:49:29Z' + name: my-user-provided-instance + tags: + - sql + type: user-provided + syslog_drain_url: http://logs.com + route_service_url: https://routes.com + relationships: + space: + data: + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133 + space: + href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 + credentials: + href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials + service_credential_bindings: + href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 + service_route_bindings: + href: https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 links: space: operationId: getSpace @@ -530,13 +821,20 @@ patch: summary: Update a service instance description: |- - Some updates can be performed entirely within the Cloud Controller in which case the response is synchronous. Some updates require communication with the service broker, in which case the response will be asynchronous. The response will be asynchronous if any of these parameters are specified: + This endpoint updates a service instance. The permitted parameters differ between `managed` and `user-provided` service instances. + + Some updates can be performed entirely within the Cloud Controller in which case the response is synchronous. + Some updates require communication with the service broker, in which case the response will be asynchronous. + The response will be asynchronous if any of these parameters are specified: + * `parameters` * `service_plan` * `maintenance_info` * `name` - when the service offering has `allow_context_updates` feature enabled Otherwise the response will be synchronous. + + **Permitted roles:** Admin, Space Developer operationId: updateServiceInstance tags: - Service Instances @@ -546,7 +844,7 @@ $ref: ../components/requestBodies/ServiceInstanceUpdateRequestBody.yaml responses: '200': - description: OK + description: Service instance updated synchronously content: application/json: schema: @@ -558,6 +856,96 @@ mapping: managed: ../components/schemas/ManagedServiceInstance.yaml user-provided: ../components/schemas/UserProvidedServiceInstance.yaml + examples: + managed_service_instance: + summary: Managed service instance + value: + guid: c89b3280-fe8d-4aa0-a42e-44465bb1c61c + created_at: '2020-03-10T15:49:29Z' + updated_at: '2020-03-10T15:49:29Z' + name: my-managed-instance + tags: [] + type: managed + maintenance_info: + version: '1.0.0' + upgrade_available: false + dashboard_url: https://service-broker.example.org/dashboard + broker_provided_metadata: + labels: + service_engine_version: '16.6' + attributes: + max_connections: '100' + last_operation: + type: update + state: succeeded + description: Operation succeeded + updated_at: '2020-03-10T15:49:32Z' + created_at: '2020-03-10T15:49:29Z' + relationships: + service_plan: + data: + guid: 5358d122-638e-11ea-afca-bf6e756684ac + space: + data: + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + metadata: + labels: + key: value + annotations: + note: detailed information + links: + self: + href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c + service_plan: + href: https://api.example.org/v3/service_plans/5358d122-638e-11ea-afca-bf6e756684ac + space: + href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 + parameters: + href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/parameters + shared_spaces: + href: https://api.example.org/v3/service_instances/c89b3280-fe8d-4aa0-a42e-44465bb1c61c/relationships/shared_spaces + service_credential_bindings: + href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c + service_route_bindings: + href: https://api.example.org/v3/service_route_bindings?service_instance_guids=c89b3280-fe8d-4aa0-a42e-44465bb1c61c + user_provided_service_instance: + summary: User-provided service instance + value: + guid: 88ce23e5-27c3-4381-a2df-32a28ec43133 + created_at: '2020-03-10T15:56:08Z' + updated_at: '2020-03-10T15:56:08Z' + last_operation: + type: create + state: succeeded + description: Operation succeeded + updated_at: '2020-03-10T15:49:32Z' + created_at: '2020-03-10T15:49:29Z' + name: my-user-provided-instance + tags: + - sql + type: user-provided + syslog_drain_url: http://logs.com + route_service_url: https://routes.com + relationships: + space: + data: + guid: 5a84d315-9513-4d74-95e5-f6a5501eeef7 + metadata: + labels: + baz: qux + annotations: + foo: bar + links: + self: + href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133 + space: + href: https://api.example.org/v3/spaces/5a84d315-9513-4d74-95e5-f6a5501eeef7 + credentials: + href: https://api.example.org/v3/service_instances/88ce23e5-27c3-4381-a2df-32a28ec43133/credentials + service_credential_bindings: + href: https://api.example.org/v3/service_credential_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 + service_route_bindings: + href: https://api.example.org/v3/service_route_bindings?service_instance_guids=88ce23e5-27c3-4381-a2df-32a28ec43133 links: space: operationId: getSpace @@ -570,13 +958,15 @@ guid: $response.body#/relationships/service_plan/data/guid description: Retrieve the service plan for this service instance (managed instances only) '202': - description: Accepted + description: Service instance update accepted; the update is being performed asynchronously headers: Location: - description: URL of the job that is updating the service instance + description: URL of the [job](#jobs) that is updating the service instance schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -598,11 +988,17 @@ description: |- This endpoint deletes a service instance and any associated service credential bindings or service route bindings. The service instance is removed from all - spaces where it is available. User provided service instances do not require interactions with service brokers, - therefore the API will respond synchronously to the delete request. For managed service instances, the API will respond asynchronously. + spaces where it is available. + + User provided service instances do not require interactions with service brokers, + therefore the API will respond synchronously to the delete request. + + For managed service instances, the API will respond asynchronously. If a service credential binding or service route binding cannot be deleted synchronously, then the operation will fail, and the deletion of the binding will continue in the background. The operation can be retried until it is successful. + + **Permitted roles:** Admin, Space Developer *(Can only purge service instances from space-scoped brokers)* operationId: deleteServiceInstance tags: - Service Instances @@ -610,20 +1006,23 @@ - $ref: ../components/parameters/Guid.yaml - name: purge in: query + required: false schema: type: boolean description: If `true`, deletes the service instance and all associated resources without any interaction with the service broker. responses: '202': - description: Accepted + description: Managed service instance deletion accepted; the instance is being deleted asynchronously headers: Location: - description: URL of the job that is deleting the service instance + description: URL of the [job](#jobs) that is deleting the service instance schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '204': - description: No Content + description: User-provided service instance deleted, or the service instance was purged '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/ServiceOfferings.yaml b/docs/openapi/apis/cf/latest/paths/ServiceOfferings.yaml index c4683e78d16..cc4433b405b 100644 --- a/docs/openapi/apis/cf/latest/paths/ServiceOfferings.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServiceOfferings.yaml @@ -1,60 +1,103 @@ /v3/service_offerings: get: summary: List service offerings - description: This endpoint retrieves the service offerings the user has access to. + description: |- + This endpoint retrieves the service offerings the user has access to. + + **Permitted roles:** All Roles, Unauthenticated Users *(for service offerings with public plans, unless `hide_marketplace_from_unauthenticated_users` is set)* operationId: listServiceOfferings tags: - Service Offerings parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service offering names to filter by + description: Comma-delimited list of names to filter by (case-insensitive) - name: available in: query + required: false schema: type: boolean description: Filter by the `available` property; valid values are `true` or `false` + - name: broker_catalog_ids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of IDs provided by the service broker for the service offering to filter by - name: service_broker_guids in: query + required: false schema: type: array items: type: string description: Comma-delimited list of service broker GUIDs to filter by - - name: space_guids + - name: service_broker_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of space guids to filter by - - name: organization_guids + description: Comma-delimited list of service broker names to filter by (case-sensitive) + - name: space_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of organization guids to filter by - - name: service_broker_names + description: Comma-delimited list of space GUIDs to filter by + - name: organization_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service broker names to filter by + description: Comma-delimited list of organization GUIDs to filter by - $ref: ../components/parameters/LabelSelector.yaml - name: fields in: query + required: false + style: deepObject + explode: true schema: type: object - description: Fields to include in the response + properties: + service_broker: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Service offerings list fields: + + Resource | Allowed Keys + --- | --- + `service_broker` | `guid`, `name` + - $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` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml responses: @@ -72,14 +115,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/service_offerings?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/service_offerings?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/service_offerings?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 name: my_service_offering description: Provides my service available: true @@ -104,7 +147,7 @@ relationships: service_broker: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 metadata: labels: {} annotations: {} @@ -115,7 +158,7 @@ href: https://api.example.org/v3/service_plans?service_offering_guids=bf7eb420-11e5-11ea-b7db-4b5d5e7976a service_broker: href: https://api.example.org/v3/service_brokers/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 20e6cd62-12bb-11ea-90d1-7bfec2c75bcd name: other_service_offering description: Provides another service available: true @@ -139,7 +182,7 @@ relationships: service_broker: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 metadata: labels: {} annotations: {} @@ -169,12 +212,35 @@ /v3/service_offerings/{guid}: get: summary: Get a service offering - description: This endpoint retrieves the service offering by GUID. + description: |- + This endpoint retrieves the service offering by GUID. + + **Permitted roles:** All Roles, Unauthenticated Users *(for service offerings with public plans, unless `hide_marketplace_from_unauthenticated_users` is set)* operationId: getServiceOffering tags: - Service Offerings parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service offering + - name: fields + in: query + required: false + style: deepObject + explode: true + schema: + type: object + properties: + service_broker: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Service offering fields: + + Resource | Allowed Keys + --- | --- + `service_broker` | `guid`, `name` responses: '200': description: OK @@ -186,7 +252,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 name: my_service_offering description: Provides my service available: true @@ -211,7 +277,7 @@ relationships: service_broker: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 metadata: labels: {} annotations: {} @@ -230,19 +296,27 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a service offering - description: This endpoint updates a service offering with labels and annotations. + description: |- + This endpoint updates a service offering with labels and annotations. + + **Permitted roles:** Admin, Space Developer *(only for service offerings from space-scoped brokers)* operationId: updateServiceOffering tags: - Service Offerings parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service offering requestBody: + description: Metadata to apply to the service offering + required: true content: application/json: schema: + type: object properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: Labels and annotations applied to the service offering examples: default: summary: default @@ -263,7 +337,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 name: my_service_offering description: Provides my service available: true @@ -288,7 +362,7 @@ relationships: service_broker: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 metadata: labels: {} annotations: {} @@ -321,13 +395,17 @@ This endpoint deletes a service offering. This is typically used to remove orphan service offerings from the Cloud Foundry database when they have been removed from the service broker catalog, or when the service broker has been removed. Note that this operation only affects the Cloud Foundry database, and no attempt is made to contact the service broker. + + **Permitted roles:** Admin, Space Developer *(only service offerings from space-scoped brokers)* operationId: deleteServiceOffering tags: - Service Offerings parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service offering - name: purge in: query + required: false schema: type: boolean description: If `true`, any service plans, instances, and bindings associated with this service offering will also be deleted diff --git a/docs/openapi/apis/cf/latest/paths/ServicePlans.yaml b/docs/openapi/apis/cf/latest/paths/ServicePlans.yaml index d95c021e73b..3ffe5e74456 100644 --- a/docs/openapi/apis/cf/latest/paths/ServicePlans.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServicePlans.yaml @@ -1,84 +1,97 @@ /v3/service_plans: get: summary: List service plans - description: This endpoint retrieves the service plans the user has access to. + description: |- + This endpoint retrieves the service plans the user has access to. + + The **organization_guids** and **space_guids** filters do not filter plans that are public. They both act on plans that are restricted to certain organizations, and to plans from space-scoped service brokers. + + **Permitted roles:** All Roles, Unauthenticated Users *(for public plans, unless `hide_marketplace_from_unauthenticated_users` is set)* operationId: listServicePlans tags: - Service Plans parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service plan names to filter by + description: Comma-delimited list of names to filter by (case-insensitive) - name: available in: query + required: false schema: type: boolean description: Filter by the `available` property; valid values are `true` or `false` - - name: service_offering_guids + - name: broker_catalog_ids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service offering guids to filter by - - name: service_instance_guids + description: Comma-delimited list of IDs provided by the service broker for the service plan to filter by + - name: space_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service instance guids to filter by - - name: space_guids + description: Comma-delimited list of space GUIDs to filter by + - name: organization_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of space guids to filter by - - name: organization_guids + description: Comma-delimited list of organization GUIDs to filter by + - name: service_broker_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of organization guids to filter by - - name: broker_catalog_ids + description: Comma-delimited list of service broker GUIDs to filter by + - name: service_broker_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of broker catalog IDs to filter by - - name: service_broker_guids + description: Comma-delimited list of service broker names to filter by (case-sensitive) + - name: service_offering_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service broker GUIDs to filter by - - name: service_broker_names + description: Comma-delimited list of service Offering GUIDs to filter by + - name: service_offering_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service broker names to filter by - - name: service_offering_names + description: Comma-delimited list of service Offering names to filter by (case-insensitive) + - name: service_instance_guids in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service offering names to filter by + description: Comma-delimited list of service Instance GUIDs to filter by - name: include in: query + required: false schema: type: array items: @@ -86,13 +99,42 @@ enum: - space.organization - service_offering - description: Optionally include a list of unique related resources in the response + description: Optionally include a list of unique related resources in the response; valid values are `space.organization` and `service_offering` + - $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`, `name` - $ref: ../components/parameters/LabelSelector.yaml - name: fields in: query + required: false + style: deepObject + explode: true schema: type: object - description: Fields to include in the response + properties: + service_offering.service_broker: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Service plans list fields: + + Resource | Allowed keys + --- | --- + `service_offering.service_broker` | `guid`, `name` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml responses: @@ -102,6 +144,113 @@ application/json: schema: $ref: ../components/schemas/ServicePlanList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/service_plans?page=1&per_page=2 + last: + href: https://api.example.org/v3/service_plans?page=2&per_page=2 + next: + href: https://api.example.org/v3/service_plans?page=2&per_page=2 + previous: null + resources: + - guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 + name: my_big_service_plan + description: Big plan + visibility_type: organization + available: true + free: false + costs: + - currency: USD + amount: 199.99 + unit: Monthly + created_at: '2019-11-28T13:44:02Z' + updated_at: '2019-11-28T13:44:02Z' + maintenance_info: + version: 1.0.0+dev4 + description: Database version 7.8.0 + broker_catalog: + id: db730a8c-11e5-11ea-838a-0f4fff3b1cfb + metadata: + custom-key: custom-value + maximum_polling_duration: null + features: + plan_updateable: true + bindable: true + schemas: + service_instance: + create: + parameters: + $schema: http://json-schema.org/draft-04/schema# + type: object + properties: + billing-account: + description: Billing account number used to charge use of shared fake server. + type: string + update: + parameters: {} + service_binding: + create: + parameters: {} + relationships: + service_offering: + data: + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 + service_offering: + href: https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 + visibility: + href: https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility + - guid: 20e6cd62-12bb-11ea-90d1-7bfec2c75bcd + name: other_service_plan + description: Provides another service plan + visibility_type: admin + available: true + free: true + created_at: '2019-11-29T16:44:02Z' + updated_at: '2019-11-29T16:44:02Z' + maintenance_info: {} + broker_catalog: + id: 3cb11822-12bb-11ea-beb1-a350dc7453b9 + metadata: + other-data: true + maximum_polling_duration: null + features: + plan_updateable: true + bindable: true + schemas: + service_instance: + create: + parameters: {} + update: + parameters: {} + service_binding: + create: + parameters: {} + relationships: + service_offering: + data: + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd + service_offering: + href: https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 + visibility: + href: https://api.example.org/v3/service_plans/20e6cd62-12bb-11ea-90d1-7bfec2c75bcd/visibility '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -121,14 +270,38 @@ /v3/service_plans/{guid}: get: summary: Get a service plan - description: This endpoint retrieves the service plan by GUID. + description: |- + This endpoint retrieves the service plan by GUID. + + **Permitted roles:** All Roles, Unauthenticated Users *(for public plans, unless `hide_marketplace_from_unauthenticated_users` is set)* operationId: getServicePlan tags: - Service Plans parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan + - name: fields + in: query + required: false + style: deepObject + explode: true + schema: + type: object + properties: + service_offering.service_broker: + type: string + description: Comma-delimited list of keys; valid values are `guid`, `name` + description: |- + [Fields parameter](#fields-parameter) used to include specific fields of related resources in the response. + + Service plan fields: + + Resource | Allowed Keys + --- | --- + `service_offering.service_broker` | `guid`, `name` - name: include in: query + required: false schema: type: array items: @@ -136,7 +309,7 @@ enum: - space.organization - service_offering - description: Optionally include a list of unique related resources in the response + description: Optionally include a list of related resources in the response; valid values are `space.organization` and `service_offering` responses: '200': description: OK @@ -148,7 +321,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 name: my_big_service_plan description: Big visibility_type: public @@ -189,7 +362,7 @@ relationships: service_offering: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 metadata: labels: {} annotations: {} @@ -208,19 +381,36 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a service plan - description: This endpoint updates a service plan with labels and annotations. + description: |- + This endpoint updates a service plan with labels and annotations. + + **Permitted roles:** Admin, Space Developer *(only for service plans from space-scoped brokers)* operationId: updateServicePlan tags: - Service Plans parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan requestBody: + description: Metadata to apply to the service plan + required: true content: application/json: schema: + type: object properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: Labels and annotations applied to the service plan + examples: + default: + summary: default + value: + metadata: + labels: + key: value + annotations: + note: detailed information responses: '200': description: OK @@ -228,6 +418,64 @@ application/json: schema: $ref: ../components/schemas/ServicePlan.yaml + examples: + default: + summary: default + value: + guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 + name: my_big_service_plan + description: Big + visibility_type: public + available: true + free: false + costs: + - currency: USD + amount: 199.99 + unit: Monthly + created_at: '2019-11-28T13:44:02Z' + updated_at: '2019-11-28T13:44:02Z' + maintenance_info: + version: 1.0.0+dev4 + description: Database version 7.8.0 + broker_catalog: + id: db730a8c-11e5-11ea-838a-0f4fff3b1cfb + metadata: + custom-key: custom-information + maximum_polling_duration: null + features: + plan_updateable: true + bindable: true + schemas: + service_instance: + create: + parameters: + $schema: http://json-schema.org/draft-04/schema# + type: object + properties: + billing-account: + description: Billing account number used to charge use of shared fake server. + type: string + update: + parameters: {} + service_binding: + create: + parameters: {} + relationships: + service_offering: + data: + guid: 13c60e38-11e7-11ea-9106-33ee3c5bd4d7 + metadata: + labels: + key: value + annotations: + note: detailed information + links: + self: + href: https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 + service_offering: + href: https://api.example.org/v3/service_offerings/13c60e38-11e7-11ea-9106-33ee3c5bd4d7 + visibility: + href: https://api.example.org/v3/service_plans/bf7eb420-11e5-11ea-b7db-4b5d5e7976a9/visibility '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -247,13 +495,15 @@ delete: summary: Delete a service plan description: |- - This endpoint deletes a service plan. This is used to remove service plans from the Cloud Foundry database when they - are no longer provided by the service broker. + This endpoint deletes a service plan. This is used to remove service plans from the Cloud Foundry database when they are no longer provided by the service broker. + + **Permitted roles:** Admin, Space Developer *(only service plans from space-scoped brokers)* operationId: deleteServicePlan tags: - Service Plans parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan responses: '204': description: No Content @@ -270,12 +520,16 @@ /v3/service_plans/{guid}/visibility: get: summary: Get a service plan visibility - description: This endpoint retrieves the service plan visibility for a given plan. + description: |- + This endpoint retrieves the service plan visibility for a given plan. + + **Permitted roles:** All Roles operationId: getServicePlanVisibility tags: - - Service Plans + - Service Plan Visibility parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan responses: '200': description: OK @@ -288,6 +542,20 @@ summary: default value: type: public + organization: + summary: organization restricted + value: + type: organization + organizations: + - guid: bf7eb420-11e5-11ea-b7db-4b5d5e7976a9 + name: my_org + space: + summary: space restricted + value: + type: space + space: + guid: ab7eb420-11e5-11ea-b7db-4b5d5e7975ad + name: my_space '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -296,12 +564,16 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a service plan visibility - description: This endpoint updates a service plan visibility. It behaves similar to the [POST service plan visibility endpoint](#apply-a-service-plan-visibility) but this endpoint will replace the existing list of organizations when the service plan is `organization` visible. + description: |- + This endpoint updates a service plan visibility. It behaves similar to the [POST service plan visibility endpoint](#apply-a-service-plan-visibility) but this endpoint will replace the existing list of organizations when the service plan is `organization` visible. + + **Permitted roles:** Admin operationId: updateServicePlanVisibility tags: - - Service Plans + - Service Plan Visibility parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan requestBody: $ref: ../components/requestBodies/ServicePlanVisibilityUpdateRequestBody.yaml responses: @@ -311,6 +583,14 @@ application/json: schema: $ref: ../components/schemas/ServicePlanVisibility.yaml + examples: + default: + summary: default + value: + type: organization + organizations: + - guid: 0fc1ad4f-e1d7-4436-8e23-6b20f03c6482 + name: other_org '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -321,12 +601,16 @@ $ref: ../components/responses/UnprocessableEntity.yaml post: summary: Apply a service plan visibility - description: This endpoint applies a service plan visibility. It behaves similar to the [PATCH service plan visibility endpoint](#update-a-service-plan-visibility) but this endpoint will append to the existing list of organizations when the service plan is `organization` visible. + description: |- + This endpoint applies a service plan visibility. It behaves similar to the [PATCH service plan visibility endpoint](#update-a-service-plan-visibility) but this endpoint will append to the existing list of organizations when the service plan is `organization` visible. + + **Permitted roles:** Admin operationId: applyServicePlanVisibility tags: - - Service Plans + - Service Plan Visibility parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan requestBody: $ref: ../components/requestBodies/ServicePlanVisibilityCreateRequestBody.yaml responses: @@ -360,18 +644,23 @@ /v3/service_plans/{guid}/visibility/{organization_guid}: delete: summary: Remove organization from a service plan visibility - description: This endpoint removes an organization from a service plan visibility list of organizations. It is only defined for service plans which are org-restricted. It will fail with a HTTP status code of 422 for any other visibility type (e.g. Public). + description: |- + This endpoint removes an organization from a service plan visibility list of organizations. It is only defined for service plans which are org-restricted. It will fail with a HTTP status code of 422 for any other visibility type (e.g. Public). + + **Permitted roles:** Admin operationId: removeOrganizationFromServicePlanVisibility tags: - - Service Plans + - Service Plan Visibility parameters: - $ref: ../components/parameters/Guid.yaml + description: The GUID of the service plan - name: organization_guid in: path required: true schema: type: string format: uuid + description: The GUID of the organization to remove from the service plan visibility responses: '204': description: No Content diff --git a/docs/openapi/apis/cf/latest/paths/ServiceRouteBindings.yaml b/docs/openapi/apis/cf/latest/paths/ServiceRouteBindings.yaml index a5ac423cc8c..bfbab5d21c4 100644 --- a/docs/openapi/apis/cf/latest/paths/ServiceRouteBindings.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServiceRouteBindings.yaml @@ -1,16 +1,17 @@ /v3/service_route_bindings: get: summary: List service route bindings - description: This endpoint retrieves the service route bindings the user has access to. + description: |- + This endpoint retrieves the service route bindings the user has access to. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listServiceRouteBindings tags: - Service Route Bindings parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - name: route_guids in: query + required: false schema: type: array items: @@ -18,6 +19,7 @@ description: Comma-delimited list of route guids to filter by - name: service_instance_guids in: query + required: false schema: type: array items: @@ -25,14 +27,16 @@ description: Comma-delimited list of service instance guids to filter by - name: service_instance_names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of service instance names to filter by + description: Comma-delimited list of service instance names to filter by (case-sensitive) - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: @@ -42,6 +46,7 @@ - $ref: ../components/parameters/UpdatedAts.yaml - name: include in: query + required: false schema: type: array items: @@ -50,13 +55,91 @@ - route - service_instance description: 'Optionally include a list of unique related resources in the response. Valid values are: `route`, `service_instance`' + - $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` and `updated_at` responses: '200': - description: OK + description: Request succeeded content: application/json: schema: $ref: ../components/schemas/ServiceRouteBindingList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/service_route_bindings?page=1&per_page=2 + last: + href: https://api.example.org/v3/service_route_bindings?page=2&per_page=2 + next: + href: https://api.example.org/v3/service_route_bindings?page=2&per_page=2 + previous: null + resources: + - guid: 4ac1a475-0f4d-4e4b-8ff6-957c94f68211 + route_service_url: https://some-route-1.api.example.org + created_at: '2020-09-08T08:55:59Z' + updated_at: '2020-09-08T08:55:59Z' + last_operation: null + metadata: + annotations: + foo: bar + labels: + baz: qux + relationships: + service_instance: + data: + guid: 39903ed2-6476-4c78-843a-0195f5fc4ccd + route: + data: + guid: 15697508-cb68-4d88-9f19-85fc53851571 + links: + self: + href: https://api.example.org/v3/service_route_bindings/4ac1a475-0f4d-4e4b-8ff6-957c94f68211 + service_instance: + href: https://api.example.org/v3/service_instances/39903ed2-6476-4c78-843a-0195f5fc4ccd + route: + href: https://api.example.org/v3/routes/15697508-cb68-4d88-9f19-85fc53851571 + parameters: + href: https://api.example.org/v3/service_route_bindings/4ac1a475-0f4d-4e4b-8ff6-957c94f68211/parameters + - guid: bdf63c4f-85af-4c20-bea9-e9def7d57dab + route_service_url: https://some-route-2.api.example.org + created_at: '2020-09-08T09:13:51Z' + updated_at: '2020-09-08T09:13:51Z' + last_operation: null + metadata: + annotations: + foo: bar + labels: + baz: qux + relationships: + service_instance: + data: + guid: f957dc7c-46d1-4a3f-973d-71ce5fdec788 + route: + data: + guid: 75ebe2a1-04b0-407b-b33c-733388fc7aa4 + links: + self: + href: https://api.example.org/v3/service_route_bindings/bdf63c4f-85af-4c20-bea9-e9def7d57dab + service_instance: + href: https://api.example.org/v3/service_instances/f957dc7c-46d1-4a3f-973d-71ce5fdec788 + route: + href: https://api.example.org/v3/routes/75ebe2a1-04b0-407b-b33c-733388fc7aa4 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -76,15 +159,22 @@ post: summary: Create a service route binding description: |- - This endpoint creates a new route service binding. The service instance and the route must be in the same space. + This endpoint creates a new route service binding. The service instance and the route + must be in the same space. + + To bind a route to a user-provided service instance, the service instance must + have the `route_service_url` property set. - To bind a route to a user-provided service instance, the service instance must have the `route_service_url` property set. + To bind a route to a managed service instance, the service offering must be bindable, + and the service offering must have `route_forwarding` set in the `requires` property. - To bind a route to a managed service instance, the service offering must be bindable, and the service offering must have `route_forwarding` set in the `requires` property. + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: createServiceRouteBinding tags: - Service Route Bindings requestBody: + description: A request to create a service route binding + required: true content: application/json: schema: @@ -101,16 +191,16 @@ relationships: route: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 7304bc3c-7010-11ea-8840-48bf6bec2d78 service_instance: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e0e4417c-74ee-11ea-a604-48bf6bec2d78 parameters: key1: value1 key2: value2 responses: '201': - description: Created + description: User-provided service instance route binding created content: application/json: schema: @@ -119,7 +209,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' route_service_url: https://route-service-url.io @@ -137,19 +227,17 @@ relationships: service_instance: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e route: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 links: self: href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e route: - href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13 - parameters: - href: https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters + href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fdd555b8f13 links: route: operationId: getRoute @@ -162,13 +250,15 @@ guid: $response.body#/relationships/service_instance/data/guid description: Retrieve the service instance for this service route binding '202': - description: Accepted + description: Managed service instance route binding creation accepted; the binding is being created asynchronously headers: Location: - description: URL of the job that is creating the service route binding + description: URL of the [job](#jobs) that is creating the service route binding schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -186,7 +276,10 @@ /v3/service_route_bindings/{guid}: get: summary: Get a service route binding - description: This endpoint retrieves the service route binding by GUID. + description: |- + This endpoint retrieves the service route binding by GUID. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getServiceRouteBinding tags: - Service Route Bindings @@ -194,6 +287,7 @@ - $ref: ../components/parameters/Guid.yaml - name: include in: query + required: false schema: type: array items: @@ -201,10 +295,10 @@ enum: - route - service_instance - description: Optionally include a list of unique related resources in the response + description: 'Optionally include a list of unique related resources in the response. Valid values are: `route`, `service_instance`' responses: '200': - description: OK + description: Request succeeded content: application/json: schema: @@ -213,7 +307,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' route_service_url: https://route-service-url.io @@ -231,19 +325,19 @@ relationships: service_instance: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e route: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 links: self: href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e route: - href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13 + href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fdd555b8f13 parameters: - href: https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters + href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters links: route: operationId: getRoute @@ -263,19 +357,26 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a service route binding - description: This endpoint updates a service route binding with labels and annotations. + description: |- + This endpoint updates a service route binding with labels and annotations. + + **Permitted roles:** Admin, Space Developer operationId: updateServiceRouteBinding tags: - Service Route Bindings parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: A request to update a service route binding + required: true content: application/json: schema: + type: object properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: Labels and annotations applied to the service route binding examples: default: summary: default @@ -287,7 +388,7 @@ note: detailed information responses: '200': - description: OK + description: Request succeeded content: application/json: schema: @@ -296,7 +397,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 created_at: '2015-11-13T17:02:56Z' updated_at: '2016-06-08T16:41:26Z' route_service_url: https://route-service-url.io @@ -314,19 +415,19 @@ relationships: service_instance: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 8bfe4c1b-9e18-45b1-83be-124163f31f9e route: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 74f7c078-0934-470f-9883-4fdd555b8f13 links: self: href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3 service_instance: href: https://api.example.org/v3/service_instances/8bfe4c1b-9e18-45b1-83be-124163f31f9e route: - href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fddss5b8f13 + href: https://api.example.org/v3/routes/74f7c078-0934-470f-9883-4fdd555b8f13 parameters: - href: https://api.example.org/v3/service_route_bindings/b3536566-63e2-428f-8f87-a1b99864ada6/parameters + href: https://api.example.org/v3/service_route_bindings/dde5ad2a-d8f4-44dc-a56f-0452d744f1c3/parameters '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -345,7 +446,13 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a service route binding - description: This endpoint deletes a service route binding. When deleting route bindings originating from user provided service instances, the delete operation does not require interactions with service brokers, therefore the API will respond synchronously to the delete request. Consequently, deleting route bindings from managed service instances responds with a job which can be used to track the progress of the delete operation. + description: |- + This endpoint deletes a service route binding. When deleting route bindings originating from user provided + service instances, the delete operation does not require interactions with service brokers, therefore the API will + respond synchronously to the delete request. Consequently, deleting route bindings from managed service instances + responds with a job which can be used to track the progress of the delete operation. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: deleteServiceRouteBinding tags: - Service Route Bindings @@ -353,15 +460,17 @@ - $ref: ../components/parameters/Guid.yaml responses: '202': - description: Accepted + description: Managed service instance route binding deletion accepted; the binding is being deleted asynchronously headers: Location: - description: URL of the job that is deleting the service route binding + description: URL of the [job](#jobs) that is deleting the service route binding schema: type: string format: uri + examples: + - https://api.example.org/v3/jobs/af5c57f6-8769-41fa-a499-2c84ed896788 '204': - description: No Content + description: User-provided service instance route binding deleted '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -375,7 +484,13 @@ /v3/service_route_bindings/{guid}/parameters: get: summary: Get parameters for a route binding - description: Queries the Service Broker for the parameters associated with this service route binding. The broker catalog must have enabled the `bindings_retrievable` feature for the Service Offering. Check the [Service Offering object](#the-service-offering-object) for the value of this feature flag. This endpoint is not available for User-Provided Service Instances. + description: |- + Queries the Service Broker for the parameters associated with this service route binding. + The broker catalog must have enabled the `bindings_retrievable` feature for the Service Offering. + Check the [Service Offering object](#the-service-offering-object) for the value of this feature flag. + This endpoint is not available for User-Provided Service Instances. + + **Permitted roles:** Admin, Admin Read-Only, Space Developer operationId: getServiceRouteBindingParameters tags: - Service Route Bindings @@ -383,17 +498,21 @@ - $ref: ../components/parameters/Guid.yaml responses: '200': - description: OK + description: Request succeeded content: application/json: schema: type: object + additionalProperties: true + description: The parameters that the service route binding was created with, as returned by the service broker examples: default: summary: default value: foo: bar foz: baz + '400': + $ref: ../components/responses/BadRequest.yaml '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/ServiceUsageEvents.yaml b/docs/openapi/apis/cf/latest/paths/ServiceUsageEvents.yaml index c4707880390..79840afcdda 100644 --- a/docs/openapi/apis/cf/latest/paths/ServiceUsageEvents.yaml +++ b/docs/openapi/apis/cf/latest/paths/ServiceUsageEvents.yaml @@ -1,30 +1,42 @@ /v3/service_usage_events: get: summary: List service usage events - description: Retrieve all service usage events the user has access to. + description: |- + Retrieve all service usage events the user has access to. + + **Permitted roles:** All Roles operationId: listServiceUsageEvents tags: - Service Usage Events parameters: - $ref: ../components/parameters/Page.yaml - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml + - name: order_by + in: query + required: false + schema: + type: string + enum: + - created_at + - -created_at + description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending; valid value is `created_at` - name: after_guid in: query - description: Filters out events before and including the event with the given guid. + required: false schema: type: string + description: Filters out events before and including the event with the given guid - name: guids in: query - description: Comma-delimited list of usage event guids to filter by. + required: false schema: type: array items: type: string + description: Comma-delimited list of usage event guids to filter by - name: service_instance_types in: query - description: Comma-delimited list of service instance types to filter by; valid values are `managed_service_instance` and `user_provided_service_instance` + required: false schema: type: array items: @@ -32,13 +44,16 @@ enum: - managed_service_instance - user_provided_service_instance + description: Comma-delimited list of service instance types to filter by; valid values are `managed_service_instance` and `user_provided_service_instance` - name: service_offering_guids in: query - description: Comma-delimited list of service offering guids to filter by + required: false schema: type: array items: type: string + description: Comma-delimited list of service offering guids to filter by + - $ref: ../components/parameters/CreatedAts.yaml responses: '200': description: OK @@ -54,11 +69,11 @@ total_results: 2 total_pages: 2 first: - href: https://api.example.org<%= path %>?page=1&per_page=1 + href: https://api.example.org/v3/service_usage_events?page=1&per_page=1 last: - href: https://api.example.org<%= path %>?page=2&per_page=1 + href: https://api.example.org/v3/service_usage_events?page=2&per_page=1 next: - href: https://api.example.org<%= path %>?page=2&per_page=1 + href: https://api.example.org/v3/service_usage_events?page=2&per_page=1 previous: null resources: - guid: 123e4567-e89b-12d3-a456-426614174000 @@ -105,12 +120,21 @@ /v3/service_usage_events/{guid}: get: summary: Get a service usage event - description: Retrieve a service usage event. + description: |- + Retrieve a service usage event. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor operationId: getServiceUsageEvent tags: - Service Usage Events parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the service usage event responses: '200': description: OK @@ -156,13 +180,24 @@ /v3/service_usage_events/actions/destructively_purge_all_and_reseed: post: summary: Purge and seed service usage events - description: Destroys all existing events. Populates new usage events, one for each existing service instance. All populated events will have a `created_at` value of current time. There is the potential race condition if service instances are currently being created or deleted. The seeded usage events will have the same guid as the service instance. + description: |- + Destroys all existing events. Populates new usage events, one for each existing service instance. All populated events will have a `created_at` value of current time. There is the potential race condition if service instances are currently being created or deleted. The seeded usage events will have the same guid as the service instance. + + **Permitted roles:** Admin operationId: purgeAndSeedServiceUsageEvents tags: - Service Usage Events responses: '200': description: OK + content: + application/json: + schema: + type: object + examples: + default: + summary: default + value: {} '400': $ref: ../components/responses/BadRequest.yaml '401': diff --git a/docs/openapi/apis/cf/latest/paths/Sidecars.yaml b/docs/openapi/apis/cf/latest/paths/Sidecars.yaml index 5e38c8e2004..f3c97bf2999 100644 --- a/docs/openapi/apis/cf/latest/paths/Sidecars.yaml +++ b/docs/openapi/apis/cf/latest/paths/Sidecars.yaml @@ -1,12 +1,21 @@ /v3/sidecars/{guid}: get: summary: Get a sidecar - description: Get a sidecar. + description: |- + Retrieve a sidecar. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getSidecar tags: - Sidecars parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the sidecar responses: '200': description: OK @@ -18,7 +27,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 name: auth-sidecar command: bundle exec rackup process_types: @@ -29,7 +38,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' links: @@ -58,12 +67,21 @@ $ref: ../components/responses/ServiceUnavailable.yaml patch: summary: Update a sidecar - description: Update a sidecar. + description: |- + Update a sidecar. + + **Permitted roles:** Admin, Space Developer operationId: updateSidecar tags: - Sidecars parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the sidecar requestBody: $ref: ../components/requestBodies/SidecarUpdateRequestBody.yaml responses: @@ -77,7 +95,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 name: auth-sidecar command: bundle exec rackup process_types: @@ -88,7 +106,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' links: @@ -115,12 +133,21 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a sidecar - description: Delete a sidecar. + description: |- + Delete a sidecar. + + **Permitted roles:** Admin, Space Developer operationId: deleteSidecar tags: - Sidecars parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the sidecar responses: '204': description: No Content @@ -137,12 +164,36 @@ /v3/apps/{guid}/sidecars: get: summary: List sidecars for app - description: Retrieves all sidecars associated with a app. + description: |- + Retrieves all sidecars associated with a app. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listAppSidecars tags: - Sidecars parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app + - $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/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml responses: '200': description: OK @@ -158,14 +209,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/apps/c7bd571f-dc48-406e-a503-3d871d659551/sidecars?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 name: auth-sidecar command: bundle exec rackup process_types: @@ -176,10 +227,10 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41921 name: echo-sidecar command: start-echo-server process_types: @@ -189,23 +240,36 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:59Z' updated_at: '2017-02-01T01:33:59Z' + '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 post: summary: Create a sidecar associated with an app - description: Create a sidecar associated with an app. + description: |- + Create a sidecar associated with an app. + + **Permitted roles:** Admin, Space Developer operationId: createSidecar tags: - Sidecars parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app requestBody: $ref: ../components/requestBodies/SidecarCreate.yaml responses: @@ -219,7 +283,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 885735b5-aea4-4cf5-8e44-961af0e41920 name: auth-sidecar command: bundle exec rackup process_types: @@ -230,7 +294,7 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' links: @@ -258,12 +322,36 @@ /v3/processes/{guid}/sidecars: get: summary: List sidecars for process - description: Retrieves all sidecars associated with a process. + description: |- + Retrieves all sidecars associated with a process. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listProcessSidecars tags: - Sidecars parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the process + - $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/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml responses: '200': description: OK @@ -279,14 +367,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/processes/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/sidecars?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 name: auth-sidecar command: bundle exec rackup process_types: @@ -297,10 +385,10 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:58Z' updated_at: '2017-02-01T01:33:58Z' - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41921 name: echo-sidecar command: start-echo-server process_types: @@ -310,12 +398,16 @@ relationships: app: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 1cb006ee-fb05-47e1-b541-c34179ddc446 created_at: '2017-02-01T01:33:59Z' updated_at: '2017-02-01T01:33:59Z' + '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 diff --git a/docs/openapi/apis/cf/latest/paths/SpaceQuotas.yaml b/docs/openapi/apis/cf/latest/paths/SpaceQuotas.yaml index 6f410fa3526..a2a9a8dcb49 100644 --- a/docs/openapi/apis/cf/latest/paths/SpaceQuotas.yaml +++ b/docs/openapi/apis/cf/latest/paths/SpaceQuotas.yaml @@ -1,14 +1,29 @@ /v3/space_quotas: get: summary: List space quotas - description: This endpoint lists all space quota resources that the user has permission to view. + description: |- + This endpoint lists all space quota resources that the user has permission to view (see [getting a space quota](#get-a-space-quota)). + + **Permitted roles:** All Roles + + > **Note:** Space quotas in the response will not show any space guids that a user would not otherwise be able to see (see [space view permissions](#get-a-space)). operationId: listSpaceQuotas tags: - Space Quotas 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` - name: guids in: query schema: @@ -22,7 +37,7 @@ type: array items: type: string - description: Comma-delimited list of space quota names to filter by + description: Comma-delimited list of space quota names to filter by (case-sensitive) - name: organization_guids in: query schema: @@ -60,7 +75,7 @@ next: null previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: f919ef8a-e333-472a-8172-baaf2c30d301 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -78,18 +93,18 @@ total_routes: 8 total_reserved_ports: 20 relationships: - organizations: + organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9b370018-c38e-44c9-86d6-155c76801104 spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 45bb0018-c38e-44c9-86d6-155c76803600 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 organization: href: https://api.example.org/v3/organizations/9b370018-c38e-44c9-86d6-155c76801104 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 554bcf32-7032-4cb0-92bc-738f9d2089d3 created_at: '2017-05-04T17:00:41Z' updated_at: '2017-05-04T17:00:41Z' name: sancho-panza @@ -107,9 +122,9 @@ total_routes: 8 total_reserved_ports: 4 relationships: - organizations: + organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9b370018-c38e-44c9-86d6-155c76801104 spaces: data: [] links: @@ -135,7 +150,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a space quota - description: This endpoint creates a new space quota scoped to a specific organization. + description: |- + This endpoint creates a new space quota scoped to a specific organization. + + **Permitted roles:** Admin, Org Manager *(Org managers can create space quotas in their managed organizations)* operationId: createSpaceQuota tags: - Space Quotas @@ -152,7 +170,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: f919ef8a-e333-472a-8172-baaf2c30d301 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -172,10 +190,10 @@ relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9b370018-c38e-44c9-86d6-155c76801104 spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 45bb0018-c38e-44c9-86d6-155c76803600 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 @@ -204,7 +222,12 @@ /v3/space_quotas/{guid}: get: summary: Get a space quota - description: Get a space quota + description: |- + This endpoint gets an individual space quota resource. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager *(Can only query space quotas owned by affiliated organizations)*, Space Auditor *(Can only query space quotas applied to affiliated spaces)*, Space Developer *(Can only query space quotas applied to affiliated spaces)*, Space Manager *(Can only query space quotas applied to affiliated spaces)*, Space Supporter *(Can only query space quotas applied to affiliated spaces)* + + > **Note:** Response will not show any space guids that a user would not otherwise be able to see (see [space view permissions](#get-a-space)). operationId: getSpaceQuota tags: - Space Quotas @@ -221,7 +244,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: f919ef8a-e333-472a-8172-baaf2c30d301 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -241,10 +264,10 @@ relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9b370018-c38e-44c9-86d6-155c76801104 spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 45bb0018-c38e-44c9-86d6-155c76803600 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 @@ -264,7 +287,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a space quota - description: This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. + description: |- + This endpoint will only update the parameters specified in the request body. Any unspecified parameters will retain their existing values. + + **Permitted roles:** Admin, Org Manager *(Can update space quotas in the organization where they have this role)* operationId: updateSpaceQuota tags: - Space Quotas @@ -283,7 +309,7 @@ default: summary: default value: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: f919ef8a-e333-472a-8172-baaf2c30d301 created_at: '2016-05-04T17:00:41Z' updated_at: '2016-05-04T17:00:41Z' name: don-quixote @@ -303,10 +329,10 @@ relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 9b370018-c38e-44c9-86d6-155c76801104 spaces: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 45bb0018-c38e-44c9-86d6-155c76803600 links: self: href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301 @@ -336,7 +362,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a space quota - description: Space quotas cannot be deleted when applied to any spaces. + description: |- + Space quotas cannot be deleted when applied to any spaces. + + **Permitted roles:** Admin, Org Manager *(Can delete space quotas within their managed organizations)* operationId: deleteSpaceQuota tags: - Space Quotas @@ -367,7 +396,9 @@ description: |- This endpoint applies a space quota to one or more spaces. - Only an admin or an org manager in the quota’s parent organization can apply a space quota to a space. + Only an admin or an org manager in the quota's parent organization can apply a space quota to a space. + + **Permitted roles:** Admin, Org Manager *(Can apply space quotas to spaces within their managed organizations)* operationId: applySpaceQuota tags: - Space Quotas @@ -378,18 +409,28 @@ schema: type: string format: uuid + description: The unique identifier for the space quota requestBody: + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToMany.yaml + type: object + required: + - data + properties: + data: + type: array + description: Space guids that the quota will apply to + items: + $ref: ../components/schemas/Relationship.yaml examples: default: summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 responses: '200': description: OK @@ -402,12 +443,12 @@ summary: default value: data: - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + - guid: 2f35885d-0c9d-4423-83ad-fd05066f8576 + - guid: 45bb0018-c38e-44c9-86d6-155c76803600 links: self: - href: https://api.example.org/v3/space_quotas/quota-guid/relationships/spaces + href: https://api.example.org/v3/space_quotas/f919ef8a-e333-472a-8172-baaf2c30d301/relationships/spaces '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -422,47 +463,27 @@ description: |- This endpoint removes a space quota from a space. - Only an admin or an org manager in the quota’s parent organization can remove a space quota from a space. + Only an admin or an org manager in the quota's parent organization can remove a space quota from a space. + + **Permitted roles:** Admin, Org Manager *(Can remove space quotas from spaces within their managed organizations)* operationId: removeSpaceQuotaFromSpace tags: - Space Quotas parameters: - - $ref: ../components/parameters/Guid.yaml - - name: space_guid + - name: guid in: path required: true schema: type: string format: uuid - 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 -/v3/space_quotas/{guid}/relationships/spaces/{space_guid}/: - delete: - summary: Remove a space quota from a space (with trailing slash) - description: |- - This endpoint removes a space quota from a space. - - Only an admin or an org manager in the quota’s parent organization can remove a space quota from a space. - operationId: removeSpaceQuotaFromSpaceWithSlash - tags: - - Space Quotas - parameters: - - $ref: ../components/parameters/Guid.yaml + description: The unique identifier for the space quota - name: space_guid in: path required: true schema: type: string format: uuid + description: The unique identifier for the space the quota will be removed from responses: '204': description: No Content diff --git a/docs/openapi/apis/cf/latest/paths/Spaces.yaml b/docs/openapi/apis/cf/latest/paths/Spaces.yaml index c06f998ad0d..0278aa0d799 100644 --- a/docs/openapi/apis/cf/latest/paths/Spaces.yaml +++ b/docs/openapi/apis/cf/latest/paths/Spaces.yaml @@ -1,26 +1,43 @@ /v3/spaces: get: summary: List spaces - description: Retrieve all spaces the user has access to. + description: |- + Retrieve all spaces the user has access to. + + **Permitted roles:** All Roles operationId: listSpaces tags: - Spaces 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`, `name` - $ref: ../components/parameters/CreatedAts.yaml - $ref: ../components/parameters/UpdatedAts.yaml - $ref: ../components/parameters/LabelSelector.yaml - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of space names to filter by + description: Comma-delimited list of space names to filter by (case-insensitive) - name: guids in: query + required: false schema: type: array items: @@ -28,6 +45,7 @@ description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false schema: type: array items: @@ -35,13 +53,14 @@ description: Comma-delimited list of organization guids to filter by - name: include in: query + required: false schema: type: array items: type: string enum: - organization - description: Optionally include a list of unique related resources in the response + description: Optionally include a list of unique related resources in the response; valid value is `organization` responses: '200': description: OK @@ -63,14 +82,15 @@ 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: space1 + suspended: false relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e00705b9-7b42-4561-ae97-2520399d2133 quota: data: null links: @@ -86,17 +106,18 @@ 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: space2 + suspended: false relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: b4ce91bd-31df-4b7d-8fd4-21a6b533276b quota: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: 6da62599-4890-4a08-8b6f-180a4f47e46b links: self: href: https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f @@ -107,7 +128,7 @@ quota: href: https://api.example.org/v3/space_quotas/6da62599-4890-4a08-8b6f-180a4f47e46b apply_manifest: - href: https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9/actions/apply_manifest + href: https://api.example.org/v3/spaces/d4c91047-7b29-4fda-b7f9-04033e5c9c9f/actions/apply_manifest method: POST metadata: labels: {} @@ -132,7 +153,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a space - description: Create a space. + description: |- + Create a space. + + **Permitted roles:** Admin, Org Manager operationId: createSpace tags: - Spaces @@ -149,14 +173,15 @@ default: summary: default value: - 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: my-space + suspended: false relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e00705b9-7b42-4561-ae97-2520399d2133 quota: data: null links: @@ -200,7 +225,10 @@ /v3/spaces/{guid}: get: summary: Get a space - description: This endpoint retrieves the specified space object. + description: |- + This endpoint retrieves the specified space object. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getSpace tags: - Spaces @@ -208,13 +236,14 @@ - $ref: ../components/parameters/Guid.yaml - name: include in: query + required: false schema: type: array items: type: string enum: - organization - description: Optionally include additional related resources in the response + description: Optionally include additional related resources in the response; valid value is `organization` responses: '200': description: OK @@ -226,14 +255,15 @@ default: summary: default value: - 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: my-space + suspended: false relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e00705b9-7b42-4561-ae97-2520399d2133 quota: data: null links: @@ -268,7 +298,10 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a space - description: Update a space + description: |- + Update a space. + + **Permitted roles:** Admin, Org Manager, Space Manager *(cannot change the `suspended` field)* operationId: updateSpace tags: - Spaces @@ -287,14 +320,15 @@ default: summary: default value: - 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: my-space + name: new-space-name + suspended: false relationships: organization: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e00705b9-7b42-4561-ae97-2520399d2133 quota: data: null links: @@ -339,7 +373,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a space - description: When a space is deleted, the user roles associated with the space will be deleted. + description: |- + When a space is deleted, the user roles associated with the space will be deleted. + + **Permitted roles:** Admin, Org Manager operationId: deleteSpace tags: - Spaces @@ -349,8 +386,8 @@ '202': description: Accepted headers: - location: - description: URL of the job to query the asynchronous operation + Location: + description: URL of the job that is deleting the space schema: type: string format: uri @@ -372,17 +409,30 @@ description: |- Apply changes specified in a manifest to the named apps and their underlying processes. The apps must reside in the space. These changes are additive and will not modify any unspecified properties or remove any existing environment variables, app features, routes, or services. - Apply manifest will only trigger an immediate update for the “instances” property or routing changes. All other properties require an app restart to take effect. + > **Note:** Apply manifest will only trigger an immediate update for the "instances" property or routing changes. All other properties require an app restart to take effect. + + **Permitted roles:** Admin, Space Developer operationId: applyManifestToSpace tags: - Spaces parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: The manifest to apply, as a YAML document + required: true content: application/x-yaml: schema: type: string + examples: + default: + summary: default + value: | + --- + applications: + - name: my-app + instances: 2 + memory: 512M responses: '202': description: Accepted @@ -403,10 +453,13 @@ /v3/spaces/{guid}/features: get: summary: List space features - description: This endpoint retrieves the list of features for the specified space. Currently, the only feature on spaces is the SSH feature. + description: |- + This endpoint retrieves the list of features for the specified space. Currently, the only feature on spaces is the SSH feature. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listSpaceFeatures tags: - - Spaces + - Space Features parameters: - $ref: ../components/parameters/Guid.yaml responses: @@ -415,7 +468,7 @@ content: application/json: schema: - $ref: ../components/schemas/SpaceFeature.yaml + $ref: ../components/schemas/SpaceFeatureList.yaml examples: default: summary: default @@ -423,9 +476,6 @@ resources: - name: ssh description: Enable SSHing into apps in the space. - enabled: true - - name: diego_docker - description: Allow Docker image support for the space. enabled: false '401': $ref: ../components/responses/Unauthorized.yaml @@ -436,10 +486,13 @@ /v3/spaces/{guid}/features/{name}: get: summary: Get a space feature - description: Get a space feature + description: |- + Retrieve the specified feature for the specified space. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getSpaceFeature tags: - - Spaces + - Space Features parameters: - $ref: ../components/parameters/Guid.yaml - name: name @@ -449,6 +502,7 @@ type: string enum: - ssh + description: Name of the space feature; the only space feature is `ssh` responses: '200': description: OK @@ -470,11 +524,14 @@ '404': $ref: ../components/responses/NotFound.yaml patch: - summary: Update a space feature - description: Update a space feature. + summary: Update space features + description: |- + Update the specified feature for the specified space. + + **Permitted roles:** Admin, Org Manager, Space Manager operationId: updateSpaceFeature tags: - - Spaces + - Space Features parameters: - $ref: ../components/parameters/Guid.yaml - name: name @@ -484,13 +541,20 @@ type: string enum: - ssh + description: Name of the space feature; the only space feature is `ssh` requestBody: + description: The new state of the space feature + required: true content: application/json: schema: + type: object properties: enabled: type: boolean + description: Denotes whether or not the space feature is enabled + required: + - enabled examples: default: summary: default @@ -525,33 +589,78 @@ This endpoint returns a JSON representation of the difference between the provided manifest and the current state of a space. Currently, this endpoint can only diff [version 1](#the-manifest-schema) manifests. + + **Permitted roles:** Admin, Space Developer operationId: createManifestDiffForSpace tags: - Spaces parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: The manifest to compare against the current state of the space, as a YAML document + required: true content: application/x-yaml: schema: type: string + examples: + default: + summary: default + value: | + --- + applications: + - name: my-app + instances: 2 + memory: 512M responses: '201': - description: Accepted - headers: - Location: - description: URL of the job that is creating the manifest diff - schema: - type: string - format: uri - '202': - description: Accepted - headers: - Location: - description: URL of the job that is creating the manifest diff + description: Created + content: + application/json: schema: - type: string - format: uri + type: object + properties: + diff: + type: array + description: The list of differences between the provided manifest and the current state of the space; the diff object format is inspired by the [JSON Patch specification](https://tools.ietf.org/html/rfc6902) + items: + type: object + properties: + op: + type: string + enum: + - add + - remove + - replace + description: Type of change; valid values are `add`, `remove`, `replace` + path: + type: string + description: Path to changing manifest field + was: + description: For `remove` and `replace` operations, the previous value; otherwise key is omitted + value: + description: For `add` and `replace` operations, the new value; otherwise key is omitted + required: + - op + - path + required: + - diff + examples: + default: + summary: default + value: + diff: + - op: remove + path: /applications/0/routes/1 + was: + route: route.example.com + - op: add + path: /applications/1/buildpacks/2 + value: java_buildpack + - op: replace + path: /applications/2/processes/1/memory + was: 256M + value: 512M '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -563,7 +672,10 @@ /v3/spaces/{guid}/relationships/isolation_segment: get: summary: Get assigned isolation segment - description: Get assigned isolation segment + description: |- + Retrieve the isolation segment assigned to the specified space. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getAssignedIsolationSegmentForSpace tags: - Spaces @@ -581,7 +693,7 @@ summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e4c91047-3b29-4fda-b7f9-04033e5a9c9f links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment @@ -596,25 +708,41 @@ patch: summary: Manage isolation segment description: |- - This endpoint assigns an isolation segment to the space. The isolation segment must be [entitled](#entitle-organizations-for-an-isolation-segment) to the space’s parent organization. + This endpoint assigns an isolation segment to the space. The isolation segment must be [entitled](#entitle-organizations-for-an-isolation-segment) to the space's parent organization. + + > **Note:** Apps will not run in the newly assigned isolation segment until they are restarted. - Apps will not run in the newly assigned isolation segment until they are restarted. + **Permitted roles:** Admin, Org Manager operationId: manageIsolationSegmentForSpace tags: - Spaces parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + description: The isolation segment relationship to assign to the space + required: true content: application/json: schema: - $ref: ../components/schemas/RelationshipToOne.yaml + type: object + properties: + data: + oneOf: + - $ref: ../components/schemas/Relationship.yaml + - type: "null" + description: Isolation segment relationship, apps will run in this isolation segment; set data to `null` to remove the relationship + required: + - data examples: default: summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e4c91047-3b29-4fda-b7f9-04033e5a9c9f + remove: + summary: remove the isolation segment + value: + data: null responses: '200': description: OK @@ -627,7 +755,7 @@ summary: default value: data: - guid: 123e4567-e89b-12d3-a456-426614174000 + guid: e4c91047-3b29-4fda-b7f9-04033e5a9c9f links: self: href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/relationships/isolation_segment @@ -644,7 +772,12 @@ /v3/spaces/{guid}/routes: delete: summary: Delete unmapped routes for a space - description: Deletes all routes in a space that are not mapped to any applications and not bound to any service instances. + description: |- + Deletes all routes in a space that are not mapped to any applications and not bound to any service instances. + + > **Note:** `unmapped=true` is a required query parameter; always include it. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: deleteUnmappedRoutesForSpace tags: - Spaces @@ -657,7 +790,7 @@ type: boolean enum: - true - description: Filter to only delete unmapped routes + description: Required query parameter; must be `true`. Only unmapped routes may be mass deleted responses: '202': description: Accepted @@ -677,8 +810,11 @@ $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. + summary: Get space usage summary + description: |- + This endpoint retrieves a usage summary for the specified space. It provides aggregated data about the space's resource usage, such as memory, routes and services. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: getUsageSummaryForSpace tags: - Spaces @@ -694,25 +830,35 @@ properties: usage_summary: type: object + description: Aggregated data about the space's resource usage properties: started_instances: type: integer + description: Total number of started app instances in the space memory_in_mb: type: integer + description: Total memory, in megabytes, used by started app instances in the space routes: type: integer + description: Total number of routes in the space service_instances: type: integer + description: Total number of managed service instances in the space reserved_ports: type: integer + description: Total number of route ports reserved by the space domains: type: integer + description: Total number of private domains owned by the space's organization per_app_tasks: type: integer + description: Total number of running and pending tasks in the space service_keys: type: integer + description: Total number of service keys in the space links: type: object + description: Links to related resources properties: self: $ref: ../components/schemas/Link.yaml @@ -736,7 +882,7 @@ links: self: href: https://api.example.org/v3/spaces/f47ac10b-58cc-4372-a567-0e02b2c3d479/usage_summary - organization: + space: href: https://api.example.org/v3/spaces/f47ac10b-58cc-4372-a567-0e02b2c3d479 '401': $ref: ../components/responses/Unauthorized.yaml @@ -747,12 +893,44 @@ /v3/spaces/{guid}/running_security_groups: get: summary: List running security groups for a space - description: This endpoint returns security groups that are enabled for running globally or at the space level for the given space. + description: |- + This endpoint returns security groups that are enabled for running globally or at the space level for the given space. + + **Permitted roles:** Admin *(can see all security groups)*, Admin Read-Only *(can see all security groups)*, Global Auditor *(can see all security groups)*, Org Manager *(can see globally-enabled security groups and groups associated with spaces in their managed organizations)*, Space Auditor *(can see globally-enabled security groups and groups associated with spaces where they have this role)*, Space Developer *(can see globally-enabled security groups and groups associated with spaces where they have this role)*, Space Manager *(can see globally-enabled security groups and groups associated with spaces where they have this role)*, Space Supporter *(can see globally-enabled security groups and groups associated with spaces where they have this role)* operationId: listRunningSecurityGroupsForSpace tags: - Spaces parameters: - $ref: ../components/parameters/Guid.yaml + - $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` + - name: guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of security group guids to filter by + - name: names + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of security group names to filter by (case-sensitive) responses: '200': description: OK @@ -760,6 +938,62 @@ application/json: schema: $ref: ../components/schemas/SecurityGroupList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 1 + total_pages: 1 + first: + href: https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50 + last: + href: https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/running_security_groups?page=1&per_page=50 + next: + previous: + resources: + - guid: b85a788e-671f-4549-814d-e34cdb2f539a + created_at: '2020-02-20T17:42:08Z' + updated_at: '2020-02-20T17:42:08Z' + name: my-group0 + globally_enabled: + running: true + staging: false + rules: + - protocol: tcp + destination: 10.10.10.0/24 + ports: '443,80,8080' + - protocol: icmp + destination: 10.10.10.0/24 + type: 8 + code: 0 + description: Allow ping requests to private services + relationships: + staging_spaces: + data: [] + running_spaces: + data: + - guid: c5048979-53b9-4d2a-9fca-78e6bc07c041 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + links: + self: + href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a + - guid: a89a788e-671f-4549-814d-e34c1b2f533a + created_at: '2020-02-20T17:42:08Z' + updated_at: '2020-02-20T17:42:08Z' + name: my-group1 + globally_enabled: + running: true + staging: true + rules: [] + relationships: + staging_spaces: + data: [] + running_spaces: + data: [] + links: + self: + href: https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -769,12 +1003,44 @@ /v3/spaces/{guid}/staging_security_groups: get: summary: List staging security groups for a space - description: This endpoint returns security groups that are enabled for staging globally or at the space level for the given space. + description: |- + This endpoint returns security groups that are enabled for staging globally or at the space level for the given space. + + **Permitted roles:** Admin *(can see all security groups)*, Admin Read-Only *(can see all security groups)*, Global Auditor *(can see all security groups)*, Org Manager *(can see globally-enabled security groups and groups associated with spaces in their managed organizations)*, Space Auditor *(can see globally-enabled security groups and groups associated with spaces where they have this role)*, Space Developer *(can see globally-enabled security groups and groups associated with spaces where they have this role)*, Space Manager *(can see globally-enabled security groups and groups associated with spaces where they have this role)*, Space Supporter *(can see globally-enabled security groups and groups associated with spaces where they have this role)* operationId: listStagingSecurityGroupsForSpace tags: - Spaces parameters: - $ref: ../components/parameters/Guid.yaml + - $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` + - name: guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of security group guids to filter by + - name: names + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of security group names to filter by (case-sensitive) responses: '200': description: OK @@ -782,6 +1048,62 @@ application/json: schema: $ref: ../components/schemas/SecurityGroupList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 1 + total_pages: 1 + first: + href: https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/staging_security_groups?page=1&per_page=50 + last: + href: https://api.example.org/v3/spaces/c5048979-53b9-4d2a-9fca-78e6bc07c041/staging_security_groups?page=1&per_page=50 + next: + previous: + resources: + - guid: b85a788e-671f-4549-814d-e34cdb2f539a + created_at: '2020-02-20T17:42:08Z' + updated_at: '2020-02-20T17:42:08Z' + name: my-group0 + globally_enabled: + running: false + staging: true + rules: + - protocol: tcp + destination: 10.10.10.0/24 + ports: '443,80,8080' + - protocol: icmp + destination: 10.10.10.0/24 + type: 8 + code: 0 + description: Allow ping requests to private services + relationships: + staging_spaces: + data: + - guid: c5048979-53b9-4d2a-9fca-78e6bc07c041 + - guid: 885735b5-aea4-4cf5-8e44-961af0e41920 + running_spaces: + data: [] + links: + self: + href: https://api.example.org/v3/security_groups/b85a788e-671f-4549-814d-e34cdb2f539a + - guid: a89a788e-671f-4549-814d-e34c1b2f533a + created_at: '2020-02-20T17:42:08Z' + updated_at: '2020-02-20T17:42:08Z' + name: my-group1 + globally_enabled: + running: true + staging: true + rules: [] + relationships: + staging_spaces: + data: [] + running_spaces: + data: [] + links: + self: + href: https://api.example.org/v3/security_groups/a89a788e-671f-4549-814d-e34c1b2f533a '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -791,12 +1113,63 @@ /v3/spaces/{guid}/users: get: summary: List users for a space - description: Retrieve all users with a role in the specified space. + description: |- + Retrieve all users with a role in the specified space. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter operationId: listUsersForSpace tags: - Spaces parameters: - $ref: ../components/parameters/Guid.yaml + - $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` and `updated_at` + - $ref: ../components/parameters/CreatedAts.yaml + - $ref: ../components/parameters/UpdatedAts.yaml + - $ref: ../components/parameters/LabelSelector.yaml + - name: guids + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of user guids to filter by + - name: usernames + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of usernames to filter by. Mutually exclusive with **partial_usernames** + - name: partial_usernames + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with **usernames** + - name: origins + in: query + required: false + schema: + type: array + items: + type: string + description: Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin "uaa"; users authenticated by an LDAP provider have the origin "ldap"; when filtering by origins, usernames must be included responses: '200': description: OK @@ -804,6 +1177,32 @@ application/json: schema: $ref: ../components/schemas/UserList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 1 + total_pages: 1 + first: + href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/users?page=1&per_page=50 + last: + href: https://api.example.org/v3/spaces/885735b5-aea4-4cf5-8e44-961af0e41920/users?page=1&per_page=50 + next: null + previous: null + resources: + - guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + username: some-name + presentation_name: some-name + origin: uaa + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 '401': $ref: ../components/responses/Unauthorized.yaml '403': diff --git a/docs/openapi/apis/cf/latest/paths/Stacks.yaml b/docs/openapi/apis/cf/latest/paths/Stacks.yaml index c69c09e0e66..c6b1d776132 100644 --- a/docs/openapi/apis/cf/latest/paths/Stacks.yaml +++ b/docs/openapi/apis/cf/latest/paths/Stacks.yaml @@ -1,24 +1,46 @@ /v3/stacks: get: summary: List stacks - description: Retrieve all stacks. + description: |- + Retrieve all stacks. + + **Permitted roles:** All Roles operationId: listStacks tags: - Stacks 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 - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of stack names to filter by + description: Comma-delimited list of stack names to filter by (case-sensitive) + - name: default + in: query + required: false + schema: + type: boolean + description: If true, only return the default stack responses: '200': description: OK @@ -34,14 +56,14 @@ total_results: 3 total_pages: 2 first: - href: https://api.example.org?page=1&per_page=2 + href: https://api.example.org/v3/stacks?page=1&per_page=2 last: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/stacks?page=2&per_page=2 next: - href: https://api.example.org?page=2&per_page=2 + href: https://api.example.org/v3/stacks?page=2&per_page=2 previous: null resources: - - guid: 123e4567-e89b-12d3-a456-426614174000 + - guid: 11c916c9-c2f9-440e-8e73-102e79c4704d created_at: '2018-11-09T22:43:28Z' updated_at: '2018-11-09T22:43:28Z' name: my-stack-1 @@ -56,8 +78,8 @@ annotations: {} links: self: - href: https://api.example.org/11c916c9-c2f9-440e-8e73-102e79c4704d - - guid: 123e4567-e89b-12d3-a456-426614174000 + href: https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d + - guid: 81c916c9-c2f9-440e-8e73-102e79c4704b created_at: '2018-11-09T22:43:29Z' updated_at: '2018-11-09T22:43:29Z' name: my-stack-2 @@ -72,7 +94,7 @@ annotations: {} links: self: - href: https://api.example.org/81c916c9-c2f9-440e-8e73-102e79c4704h + href: https://api.example.org/v3/stacks/81c916c9-c2f9-440e-8e73-102e79c4704b '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -91,7 +113,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml post: summary: Create a stack - description: Create a stack. + description: |- + Create a stack. + + **Permitted roles:** Admin operationId: createStack tags: - Stacks @@ -104,6 +129,26 @@ application/json: schema: $ref: ../components/schemas/Stack.yaml + examples: + default: + summary: default + value: + guid: 11c916c9-c2f9-440e-8e73-102e79c4704d + created_at: '2018-11-09T22:43:28Z' + updated_at: '2018-11-09T22:43:28Z' + name: my-stack + description: Here is my stack! + state: ACTIVE + state_reason: null + build_rootfs_image: my-stack + run_rootfs_image: my-stack + default: true + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -121,7 +166,10 @@ /v3/stacks/{guid}: get: summary: Get a stack - description: Get a stack. + description: |- + Retrieve a stack. + + **Permitted roles:** All Roles operationId: getStack tags: - Stacks @@ -134,6 +182,26 @@ application/json: schema: $ref: ../components/schemas/Stack.yaml + examples: + default: + summary: default + value: + guid: 11c916c9-c2f9-440e-8e73-102e79c4704d + created_at: '2018-11-09T22:43:28Z' + updated_at: '2018-11-09T22:43:28Z' + name: my-stack + description: Here is my stack! + state: ACTIVE + state_reason: null + build_rootfs_image: my-stack + run_rootfs_image: my-stack + default: true + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -142,19 +210,36 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a stack - description: Update a stack. + description: |- + Update a stack. + + **Permitted roles:** Admin operationId: updateStack tags: - Stacks parameters: - $ref: ../components/parameters/Guid.yaml requestBody: + required: true content: application/json: schema: + type: object properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: Labels and annotations applied to the stack + state: + type: string + enum: + - ACTIVE + - RESTRICTED + - DEPRECATED + - DISABLED + description: 'The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`' + state_reason: + type: [string, "null"] + description: Optional plain text describing the stack state change examples: default: summary: default @@ -173,6 +258,28 @@ application/json: schema: $ref: ../components/schemas/Stack.yaml + examples: + default: + summary: default + value: + guid: 11c916c9-c2f9-440e-8e73-102e79c4704d + created_at: '2018-11-09T22:43:28Z' + updated_at: '2018-11-09T22:43:28Z' + name: my-stack + description: Here is my stack! + state: DISABLED + state_reason: Stack disabled and cannot be used for staging new application + build_rootfs_image: my-stack + run_rootfs_image: my-stack + default: true + metadata: + labels: + key: value + annotations: + note: detailed information + links: + self: + href: https://api.example.org/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -191,7 +298,10 @@ $ref: ../components/responses/ServiceUnavailable.yaml delete: summary: Delete a stack - description: Delete a stack. + description: |- + Delete a stack. + + **Permitted roles:** Admin operationId: deleteStack tags: - Stacks @@ -213,7 +323,10 @@ /v3/stacks/{guid}/apps: get: summary: List apps on a stack - description: Retrieve all apps using a given stack. + description: |- + Retrieve all apps using a given stack. + + **Permitted roles:** All Roles operationId: listAppsOnStack tags: - Stacks @@ -221,7 +334,19 @@ - $ref: ../components/parameters/Guid.yaml - $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 @@ -312,7 +437,7 @@ space: data: guid: 123e4567-e89b-12d3-a456-426614174000 - droplet: + current_droplet: data: guid: 123e4567-e89b-12d3-a456-426614174000 links: diff --git a/docs/openapi/apis/cf/latest/paths/Tasks.yaml b/docs/openapi/apis/cf/latest/paths/Tasks.yaml index e8056d0a36d..753a721db00 100644 --- a/docs/openapi/apis/cf/latest/paths/Tasks.yaml +++ b/docs/openapi/apis/cf/latest/paths/Tasks.yaml @@ -1,19 +1,17 @@ /v3/tasks: get: summary: List tasks - description: Retrieve all tasks the user has access to. The `command` field is excluded in the response. + description: |- + Retrieve all tasks the user has access to. The `command` field is excluded in the response. + + **Permitted roles:** All Roles operationId: listTasks tags: - Tasks parameters: - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - - $ref: ../components/parameters/LabelSelector.yaml - name: guids in: query + required: false schema: type: array items: @@ -21,13 +19,15 @@ description: Comma-delimited list of task guids to filter by - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of task names to filter by + description: Comma-delimited list of task names to filter by (case-insensitive) - name: states in: query + required: false schema: type: array items: @@ -41,6 +41,7 @@ description: Comma-delimited list of task states to filter by - name: app_guids in: query + required: false schema: type: array items: @@ -48,6 +49,7 @@ description: Comma-delimited list of app guids to filter by - name: space_guids in: query + required: false schema: type: array items: @@ -55,18 +57,28 @@ description: Comma-delimited list of space guids to filter by - name: organization_guids in: query + required: false schema: type: array items: type: string description: Comma-delimited list of organization guids to filter by - - name: sequence_ids + - $ref: ../components/parameters/Page.yaml + - $ref: ../components/parameters/PerPage.yaml + - name: order_by in: query + required: false schema: - type: array - items: - type: integer - description: Comma-delimited list of sequence ids to filter by + 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 @@ -74,6 +86,81 @@ application/json: schema: $ref: ../components/schemas/TaskList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/tasks?page=1&per_page=2 + last: + href: https://api.example.org/v3/tasks?page=2&per_page=2 + next: + href: https://api.example.org/v3/tasks?page=2&per_page=2 + previous: null + resources: + - guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: hello + user: vcap + state: SUCCEEDED + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a + - guid: 63b4cd89-fd8b-4bf1-a311-7174fcc907d6 + sequence_id: 2 + name: migrate + user: vcap + state: FAILED + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: Exited with status 1 + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6 + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -93,20 +180,24 @@ /v3/apps/{guid}/tasks: get: summary: List tasks for an app - description: Retrieve tasks for an app. + description: |- + Retrieve tasks for an app the user has access to. The `command` field may be excluded in the response based on the user's role. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(`command` field redacted)*, Org Manager *(`command` field redacted)*, Space Auditor *(`command` field redacted)*, Space Developer, Space Manager *(`command` field redacted)*, Space Supporter *(`command` field redacted)* operationId: listAppTasks tags: - Tasks parameters: - - $ref: ../components/parameters/Guid.yaml - - $ref: ../components/parameters/Page.yaml - - $ref: ../components/parameters/PerPage.yaml - - $ref: ../components/parameters/OrderBy.yaml - - $ref: ../components/parameters/CreatedAts.yaml - - $ref: ../components/parameters/UpdatedAts.yaml - - $ref: ../components/parameters/LabelSelector.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app - name: guids in: query + required: false schema: type: array items: @@ -114,13 +205,15 @@ description: Comma-delimited list of task guids to filter by - name: names in: query + required: false schema: type: array items: type: string - description: Comma-delimited list of task names to filter by + description: Comma-delimited list of task names to filter by (case-insensitive) - name: states in: query + required: false schema: type: array items: @@ -134,11 +227,28 @@ description: Comma-delimited list of task states to filter by - name: sequence_ids in: query + required: false schema: type: array items: type: integer - description: Comma-delimited list of sequence ids to filter by + description: Comma delimited list of sequence ids to filter by Valid values are integers >= 1 + - $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 @@ -146,20 +256,108 @@ application/json: schema: $ref: ../components/schemas/TaskList.yaml + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=1&per_page=2 + last: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2 + next: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5/tasks?page=2&per_page=2 + previous: null + resources: + - guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: hello + user: vcap + state: SUCCEEDED + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a + - guid: 63b4cd89-fd8b-4bf1-a311-7174fcc907d6 + sequence_id: 2 + name: migrate + user: vcap + state: FAILED + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: Exited with status 1 + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6 + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/63b4cd89-fd8b-4bf1-a311-7174fcc907d6/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a + '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 post: summary: Create a task - description: Create a task. + description: |- + Create a task for an app. + + **Permitted roles:** Admin, Space Developer operationId: createTask tags: - Tasks parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the app requestBody: $ref: ../components/requestBodies/TaskCreateRequestBody.yaml responses: @@ -169,6 +367,41 @@ application/json: schema: $ref: ../components/schemas/Task.yaml + examples: + default: + summary: default + value: + guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: migrate + command: rake db:migrate + user: vcap + state: RUNNING + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a links: app: operationId: getApp @@ -199,12 +432,21 @@ /v3/tasks/{guid}: get: summary: Get a task - description: Retrieve a task. The `command` field may be excluded in the response based on the user’s role. + description: |- + Retrieve a specific task. The `command` field may be excluded in the response based on the user's role. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor *(`command` field redacted)*, Org Manager *(`command` field redacted)*, Space Auditor *(`command` field redacted)*, Space Developer, Space Manager *(`command` field redacted)*, Space Supporter *(`command` field redacted)* operationId: getTask tags: - Tasks parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the task responses: '200': description: OK @@ -212,6 +454,41 @@ application/json: schema: $ref: ../components/schemas/Task.yaml + examples: + default: + summary: default + value: + guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: migrate + command: rake db:migrate + user: vcap + state: RUNNING + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a links: app: operationId: getApp @@ -231,19 +508,36 @@ $ref: ../components/responses/NotFound.yaml patch: summary: Update a task - description: Update a task. + description: |- + Update a task's metadata. + + **Permitted roles:** Admin, Space Developer operationId: updateTask tags: - Tasks parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the task requestBody: + description: The task fields to update + required: true content: application/json: schema: + type: object properties: metadata: $ref: ../components/schemas/Metadata.yaml + description: |- + `labels`: Labels applied to the task + + `annotations`: Annotations applied to the task + description: Request schema for updating a task examples: default: summary: default @@ -260,6 +554,43 @@ application/json: schema: $ref: ../components/schemas/Task.yaml + examples: + default: + summary: default + value: + guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: migrate + command: rake db:migrate + user: vcap + state: RUNNING + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: + key: value + annotations: + note: detailed information + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -279,19 +610,69 @@ /v3/tasks/{guid}/actions/cancel: post: summary: Cancel a task - description: Cancels a running task. Canceled tasks will initially be in state `CANCELING` and will move to state `FAILED` once the cancel request has been processed. Cancel requests are idempotent and will be processed according to the state of the task when the request is executed. Canceling a task that is in `SUCCEEDED` or `FAILED` state will return an error. + description: |- + Cancels a running task. + + Canceled tasks will initially be in state `CANCELING` and will move to state `FAILED` once the cancel request has been processed. + + Cancel requests are idempotent and will be processed according to the state of the task when the request is executed. + + Canceling a task that is in `SUCCEEDED` or `FAILED` state will return an error. + + **Permitted roles:** Admin, Space Developer, Space Supporter operationId: cancelTask tags: - Tasks parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the task responses: '202': - description: OK + description: Accepted content: application/json: schema: $ref: ../components/schemas/Task.yaml + examples: + default: + summary: default + value: + guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: migrate + command: rake db:migrate + user: vcap + state: CANCELING + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a '401': $ref: ../components/responses/Unauthorized.yaml '403': @@ -300,21 +681,75 @@ $ref: ../components/responses/NotFound.yaml '422': $ref: ../components/responses/UnprocessableEntity.yaml +/v3/tasks/{guid}/cancel: put: - summary: Cancel a task (PUT) - description: Cancels a running task using PUT method. Canceled tasks will initially be in state `CANCELING` and will move to state `FAILED` once the cancel request has been processed. Cancel requests are idempotent and will be processed according to the state of the task when the request is executed. Canceling a task that is in `SUCCEEDED` or `FAILED` state will return an error. - operationId: cancelTaskPut + summary: Cancel a task (deprecated) + description: |- + Cancels a running task. + + Canceled tasks will initially be in state `CANCELING` and will move to state `FAILED` once the cancel request has been processed. + + Cancel requests are idempotent and will be processed according to the state of the task when the request is executed. + + Canceling a task that is in `SUCCEEDED` or `FAILED` state will return an error. + + > **Warning:** This endpoint is deprecated. Use `POST /v3/tasks/:guid/actions/cancel` instead. + + **Permitted roles:** Admin, Space Developer, Space Supporter + operationId: cancelTaskShort tags: - Tasks + deprecated: true parameters: - - $ref: ../components/parameters/Guid.yaml + - name: guid + in: path + required: true + schema: + type: string + format: uuid + description: The unique identifier for the task responses: '202': - description: OK + description: Accepted content: application/json: schema: $ref: ../components/schemas/Task.yaml + examples: + default: + summary: default + value: + guid: d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + sequence_id: 1 + name: migrate + command: rake db:migrate + user: vcap + state: CANCELING + memory_in_mb: 512 + disk_in_mb: 1024 + log_rate_limit_in_bytes_per_second: 1024 + result: + failure_reason: null + droplet_guid: 740ebd2b-162b-469a-bd72-3edb96fabd9a + metadata: + labels: {} + annotations: {} + created_at: '2016-05-04T17:00:41Z' + updated_at: '2016-05-04T17:00:42Z' + relationships: + app: + data: + guid: ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + links: + self: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa + app: + href: https://api.example.org/v3/apps/ccc25a0f-c8f4-4b39-9f1b-de9f328d0ee5 + cancel: + href: https://api.example.org/v3/tasks/d5cc22ec-99a3-4e6a-af91-a44b4ab7b6fa/actions/cancel + method: POST + droplet: + href: https://api.example.org/v3/droplets/740ebd2b-162b-469a-bd72-3edb96fabd9a '400': $ref: ../components/responses/BadRequest.yaml '401': @@ -327,27 +762,3 @@ $ref: ../components/responses/UnprocessableEntity.yaml '500': $ref: ../components/responses/500.yaml -/v3/tasks/{guid}/cancel: - put: - summary: DEPRECATED - Cancel a task (short path) - description: DEPRECATED - Use /v3/tasks/{guid}/actions/cancel instead. - operationId: cancelTaskShort - tags: - - Tasks - parameters: - - $ref: ../components/parameters/Guid.yaml - responses: - '202': - description: OK - content: - application/json: - schema: - $ref: ../components/schemas/Task.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 diff --git a/docs/openapi/apis/cf/latest/paths/Users.yaml b/docs/openapi/apis/cf/latest/paths/Users.yaml index f844746ebd3..dd39c68fa01 100644 --- a/docs/openapi/apis/cf/latest/paths/Users.yaml +++ b/docs/openapi/apis/cf/latest/paths/Users.yaml @@ -1,14 +1,27 @@ /v3/users: get: summary: List users - description: Retrieve all users that the current user can see. + description: |- + Retrieve all users that the current user can see. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor *(Can only view users affiliated with their org)*, Org Billing Manager *(Can only view users affiliated with their org)*, Org Manager *(Can only view users affiliated with their org)*, Space Auditor *(Can only view users affiliated with their org)*, Space Developer *(Can only view users affiliated with their org)*, Space Manager *(Can only view users affiliated with their org)*, Space Supporter *(Can only view users affiliated with their org)* operationId: listUsers tags: - Users 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` and `updated_at` - $ref: '../components/parameters/CreatedAts.yaml' - $ref: '../components/parameters/UpdatedAts.yaml' - $ref: '../components/parameters/LabelSelector.yaml' @@ -18,28 +31,28 @@ type: array items: type: string - description: Comma-delimited list of user guids to filter by (can include UAA user IDs or client IDs) + description: Comma-delimited list of user guids to filter by - name: usernames in: query schema: type: array items: type: string - description: Comma-delimited list of usernames to filter by - - name: origins + description: Comma-delimited list of usernames to filter by. Mutually exclusive with **partial_usernames** + - name: partial_usernames in: query schema: type: array items: type: string - description: Comma-delimited list of user origins to filter by - - name: partial_usernames + description: Comma-delimited list of strings to search by. When using this query parameter, all the users that contain the string provided in their username will be returned. Mutually exclusive with **usernames** + - name: origins in: query schema: type: array items: type: string - description: Comma-delimited list of partial usernames to filter by + description: Comma-delimited list of user origins (user stores) to filter by, for example, users authenticated by UAA have the origin "uaa"; users authenticated by an LDAP provider have the origin "ldap"; when filtering by origins, usernames must be included responses: '200': description: OK @@ -47,6 +60,45 @@ application/json: schema: $ref: '../components/schemas/UserList.yaml' + examples: + default: + summary: default + value: + pagination: + total_results: 3 + total_pages: 2 + first: + href: https://api.example.org/v3/users?page=1&per_page=2 + last: + href: https://api.example.org/v3/users?page=2&per_page=2 + next: + href: https://api.example.org/v3/users?page=2&per_page=2 + previous: null + resources: + - guid: client_id + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + username: null + presentation_name: client_id + origin: null + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/client_id + - guid: 9da93b89-3f89-4f05-7238-8a2b123c79l9 + created_at: '2019-03-08T01:06:19Z' + updated_at: '2019-03-08T01:06:19Z' + username: some-name + presentation_name: some-name + origin: uaa + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/9da93b89-3f89-4f05-7238-8a2b123c79l9 '400': $ref: '../components/responses/BadRequest.yaml' '401': @@ -65,20 +117,20 @@ $ref: '../components/responses/Conflict.yaml' post: summary: Create a user - description: 'Creating a user requires one value, a GUID. This creates a user - in the Cloud Controller database. - + description: |- + Creating a user requires one value, a GUID. This creates a user in the Cloud + Controller database. - Generally, the GUID should match the GUID of an already-created user in the - UAA database, though this is not required. Creating a user by guid is only permitted - by admins. + Generally, the GUID should match the ID of an already-created user in the UAA + database, though this is not required. The GUID can also be a UAA client ID, to + support the UAA `client_credentials` grant type. Creating a user by guid is + only permitted by admins. + If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, a UAA user will be automatically created if it does not exist yet. + The UAA user will be only created when `username` and `origin` have been provided instead of a guid. Additionally `origin` must be different from `uaa`. + Admins and OrgManagers can make use of the UAA user creation. - If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, a UAA user - will be automatically created if it does not exist yet. The UAA user will be - only created when `username` and `origin` have been provided instead of a guid. - Additionally `origin` must be different from `uaa`. Admins and OrgManagers can - make use of the UAA user creation.' + **Permitted roles:** Admin, OrgManager *(can only create users by `username` and `origin` and when CAPI property `cc.allow_user_creation_by_org_manager` is enabled)* operationId: createUser tags: - Users @@ -106,7 +158,12 @@ /v3/users/{guid}: get: summary: Get a user - description: Retrieve a user. + description: |- + Retrieve a user. + + **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor *(Can only view users affiliated with their org)*, Org Billing Manager *(Can only view users affiliated with their org)*, Org Manager *(Can only view users affiliated with their org)*, Space Auditor *(Can only view users affiliated with their org)*, Space Developer *(Can only view users affiliated with their org)*, Space Manager *(Can only view users affiliated with their org)*, Space Supporter *(Can only view users affiliated with their org)* + + > **Note:** A user can always see themselves with this endpoint, regardless of role. operationId: getUser tags: - Users @@ -119,6 +176,22 @@ application/json: schema: $ref: '../components/schemas/User.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' + username: some-name + presentation_name: some-name + origin: uaa + metadata: + labels: {} + annotations: {} + links: + self: + href: https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5 '401': $ref: '../components/responses/Unauthorized.yaml' '404': @@ -127,7 +200,10 @@ $ref: '../components/responses/Forbidden.yaml' patch: summary: Update a user - description: Update a user's metadata. + description: |- + Update a user's metadata. + + **Permitted roles:** Admin operationId: updateUser tags: - Users @@ -156,7 +232,10 @@ $ref: '../components/responses/Conflict.yaml' delete: summary: Delete a user - description: All roles associated with a user will be deleted if the user is deleted. + description: |- + All roles associated with a user will be deleted if the user is deleted. + + **Permitted roles:** Admin operationId: deleteUser tags: - Users diff --git a/docs/openapi/apis/cf/latest/paths/V3.yaml b/docs/openapi/apis/cf/latest/paths/V3.yaml index 13181f70e22..aae9dcbf31b 100644 --- a/docs/openapi/apis/cf/latest/paths/V3.yaml +++ b/docs/openapi/apis/cf/latest/paths/V3.yaml @@ -1,10 +1,13 @@ get: - summary: Get V3 API root + summary: V3 API Root description: |- - Returns the V3 API root endpoint information. + This endpoint returns links to all the resources available on the v3 API. + + **Authentication:** No authentication required. operationId: getV3ApiRoot tags: - Root + security: [] responses: '200': description: OK @@ -21,10 +24,22 @@ get: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the current endpoint + app_usage_events: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the app usage events endpoint apps: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the apps endpoint + audit_events: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the audit events endpoint + buildpacks: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the buildpacks endpoint builds: allOf: - $ref: '../components/schemas/Link.yaml' @@ -41,6 +56,10 @@ get: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the droplets endpoint + environment_variable_groups: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the environment variable groups endpoint feature_flags: allOf: - $ref: '../components/schemas/Link.yaml' @@ -57,6 +76,10 @@ get: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the organizations endpoint + organization_quotas: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the organization quotas endpoint packages: allOf: - $ref: '../components/schemas/Link.yaml' @@ -65,6 +88,10 @@ get: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the processes endpoint + resource_matches: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the resource matches endpoint roles: allOf: - $ref: '../components/schemas/Link.yaml' @@ -84,7 +111,12 @@ get: service_instances: allOf: - $ref: '../components/schemas/Link.yaml' - - description: Link to the service instances endpoint + - type: object + properties: + experimental: + type: boolean + description: Indicates that the resource is experimental and subject to change + description: Link to the service instances endpoint service_offerings: allOf: - $ref: '../components/schemas/Link.yaml' @@ -93,10 +125,18 @@ get: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the service plans endpoint + service_usage_events: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the service usage events endpoint spaces: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the spaces endpoint + space_quotas: + allOf: + - $ref: '../components/schemas/Link.yaml' + - description: Link to the space quotas endpoint stacks: allOf: - $ref: '../components/schemas/Link.yaml' @@ -109,6 +149,74 @@ get: allOf: - $ref: '../components/schemas/Link.yaml' - description: Link to the users endpoint + examples: + default: + summary: default + value: + links: + self: + href: https://api.example.org/v3 + app_usage_events: + href: https://api.example.org/v3/app_usage_events + apps: + href: https://api.example.org/v3/apps + audit_events: + href: https://api.example.org/v3/audit_events + buildpacks: + href: https://api.example.org/v3/buildpacks + builds: + href: https://api.example.org/v3/builds + deployments: + href: https://api.example.org/v3/deployments + domains: + href: https://api.example.org/v3/domains + droplets: + href: https://api.example.org/v3/droplets + environment_variable_groups: + href: https://api.example.org/v3/environment_variable_groups + feature_flags: + href: https://api.example.org/v3/feature_flags + info: + href: https://api.example.org/v3/info + isolation_segments: + href: https://api.example.org/v3/isolation_segments + organizations: + href: https://api.example.org/v3/organizations + organization_quotas: + href: https://api.example.org/v3/organization_quotas + packages: + href: https://api.example.org/v3/packages + processes: + href: https://api.example.org/v3/processes + resource_matches: + href: https://api.example.org/v3/resource_matches + roles: + href: https://api.example.org/v3/roles + routes: + href: https://api.example.org/v3/routes + security_groups: + href: https://api.example.org/v3/security_groups + service_brokers: + href: https://api.example.org/v3/service_brokers + service_instances: + href: https://api.example.org/v3/service_instances + experimental: true + service_offerings: + href: https://api.example.org/v3/service_offerings + service_plans: + href: https://api.example.org/v3/service_plans + service_usage_events: + href: https://api.example.org/v3/service_usage_events + spaces: + href: https://api.example.org/v3/spaces + space_quotas: + href: https://api.example.org/v3/space_quotas + stacks: + href: https://api.example.org/v3/stacks + tasks: + href: https://api.example.org/v3/tasks + users: + href: https://api.example.org/v3/users '404': $ref: '../components/responses/NotFound.yaml' '500':