Skip to content

Latest commit



219 lines (174 loc) · 16.8 KB

File metadata and controls

219 lines (174 loc) · 16.8 KB

Service Broker API Release Notes

  • Add binding rotation fields to the spec and guidance on how to use the expiration fields for service binding
  • Remove ambiguity on provisioning status code and clarify 200 status with consistent language for depraction
  • Add context object to the response of fetching a service instance and turn into a non-requirement for service instances
  • Rename context to attributes and update openapi files and the spec with an example
  • Moved attributes to metadata and returns the metadata on fetch
  • Add guidance for orphan mitigation
  • Reconcile openapi and swagger files to match and generate identical clients and servers
  • Add guidance for remembering the state of service instance and service binding operations
  • Add guidance to handle 500 errors from Service Instance update
  • Add guidance to handle requests with invalid data
  • Allow Service Brokers to indicate if a Service Instance is still usable after a failed update or deprovisioning and if an update can be repeated
  • Specify that Platforms SHOULD NOT reuse IDs
  • Allow the platform to supply Service ID and Plan ID as hints when retrieving a service binding or a service instance
  • Add CF and K8s annotations to the profile document
  • Add support for ETag and If-Modified-Since headers
  • Clarify the response code when Platform does not provide the required API version header
  • Service Instances can be labelled with information defined by the Service Broker
  • Add expiration date and time for bindings



  • Added GET endpoints for fetching a Service Instance and Service Binding
  • Added support for asynchronous Service Bindings (PR) and a new last operation endpoint for Service Bindings endpoint
  • Added clarity around concurrent updates (PR)
  • Added clarity on how Platform's can clean up after a failed provision or bind (PR)
  • Added Opaque Bearer Tokens to the Platform to Service Broker Authentication section (PR)
  • Provided guidance for CLI-friendly names (PR)
  • Allow for uppercase characters in Service and Service Plan names (PR)
  • Clarify that extra fields in requests and responses are allowed (PR)
  • Allow an updated dashboard_url to be provided when updating a Service Instance (PR)
  • Added an OpenAPI 2.0 implementation
  • Allow for periods in name fields (PR)
  • Removed the need for Platforms to perform orphan mitigation when receiving an HTTP 408 response code (PR)
  • Moved the dashboard_client field to Cloud Foundry Catalog Extensions
  • Added a compatibility matrix describing which optional features in the specification are supported by different Platforms
  • Added clarity for returning Service Binding information via the GET endpoints (PR)
  • Added guidance for supported string lengths (PR)
  • Clarified that the plan_updateable field affects modifying the Service Plan, not parameters (PR)
  • Clarified which Service Plan ID to use for polling the last operation endpoint after an update (PR)
  • Clarified Platform behaviour when a dashboard URL is not returned (PR)
  • Fixed an incompatible change introduced in v2.12 (PR)
  • Added clarity around the state of resources after a failure (PR)
  • Added Content Type guidelines



  • Added context field to request body for provisioning a service instance (PUT /v2/service_instances/:instance_id) and updating a service instance (PATCH /v2/service_instances/:instance_id). Also added the file describing RECOMMENDED usage patterns for environment-specific extensions and variations. context will replace the organization_guid and space_guid request fields in future versions of the specification. In the interim, both SHOULD be used to ensure interoperability with old and new implementations.
  • The specification now uses RFC2119 keywords to make it clearer when things are REQUIRED rather than OPTIONAL or RECOMMENDED.
  • Request and response parameters of type string, if present, MUST be a non-empty string.
  • Cleaned up text around status codes in responses, clarifying when they MUST be returned.
  • Added clarity around the app_guid request field.
  • Clarified the semantics of plan_id and parameters fields in the updating a service instance request body.
  • Clarified the default value of the plan_updateable field.
  • Clarified when route_service_url is REQUIRED and when brokers can return extra data in bindings.


  • Added field bindable to plan objects in /v2/catalog response. This allows services to have both bindable and non-bindable plans.


  • Service bind responses now include an optional field called volume_mounts. Backward incompatible changes to volume_mounts field in service bind response from experimental 2.9 format to final format.


  • last_operation endpoint now supports service_id and plan_id as request parameters.

  • A new field operation may now be returned by brokers in asynchronous responses for Provision, Update, Deprovision. This field enables brokers to provide an internal identifier for the operation that clients should provide back to the service broker when polling the last_operation endpoint.


  • In support for Route Services, service broker may now return a route_service_url in the response for a create binding request.

  • A broker must specify requires: ["route_forwarding"] in its catalog endpoint if it supports Route Services.

  • Clients may now send a new field bind_resource with the bind request, under which the parameters required for the binding are found. This would include, for example, app_guid for an app binding and route for a route binding. For backwards compatibility, app_guid will remain a top-level key in addition to being included in the bind_resource.


  • Added support for Asynchronous Operations. Brokers may now return a 202 Accepted in response to provision, update, or deprovision requests to indicate the requested operation is in progress.

  • The parameter accepts_incomplete=true must be passed by the broker client with requests for provision, update, or deprovision to indicate support for an asynchronous response. The broker can then choose to execute the request synchronously or asynchronously.

  • Added support for querying last_operation status at a new endpoint: GET /v2/service_instances/:guid/last_operation



  • app_guid field is no longer guaranteed to be included with create service binding requests

  • New field service_id is required with update service instance requests



  • Added support for Arbitrary Parameters: service-specific configuration parameters that can be included with provision, update and bind requests



  • Added support for broker clients to change the service plan for a specified service instance using new Update Service Instance endpoint



  • Added dashboard_client field to /v2/catalog to enable broker client to provision OAuth client for a service dashboard



  • Added field free for service plan in catalog endpoint



  • New field app_guid is required with bind requests