From 83d7dd978385d604f15a1f40122b04603af1f9a2 Mon Sep 17 00:00:00 2001 From: Eric Saxby Date: Tue, 17 May 2016 11:51:18 -0700 Subject: [PATCH 1/6] Update Last Operation docs to include parameters - Bump Service Broker API version to 2.9 [#114769745] Signed-off-by: Rizwan Reza Signed-off-by: Stev Witzel --- _version_table.html.erb | 3 +- api-v2.8.html.md.erb | 1209 +++++++++++++++++++++++++++++++++++++++ api.html.md.erb | 60 +- 3 files changed, 1255 insertions(+), 17 deletions(-) create mode 100644 api-v2.8.html.md.erb diff --git a/_version_table.html.erb b/_version_table.html.erb index 92be5fc..6a15991 100644 --- a/_version_table.html.erb +++ b/_version_table.html.erb @@ -16,9 +16,10 @@ brokers are upgraded. - 2.8
+ 2.9
+ 2.8
2.7
2.6
2.5
diff --git a/api-v2.8.html.md.erb b/api-v2.8.html.md.erb new file mode 100644 index 0000000..628847f --- /dev/null +++ b/api-v2.8.html.md.erb @@ -0,0 +1,1209 @@ +--- +title: Service Broker API v2.8 +owner: Services API +--- + +<%= modified_date %> + +## Document Changelog ## + +[v2 API Change Log](v2-api-changelog.html) + +<%= partial "version_table.html" %> + +## Changes ## + +### Change Policy ### + +* Existing endpoints and fields will not be removed or renamed. +* New optional endpoints, or new HTTP methods for existing endpoints, may be +added to enable support for new features. +* New fields may be added to existing request/response messages. +These fields must be optional and should be ignored by clients and servers +that do not understand them. + +### Changes Since v2.7 ### + +1. Brokers may now include a requires: ["route_forwarding"] on their catalog endpoint. +1. On bind, the Cloud Controller will now send a new top-level key, `bind_resource`, under which the required parameters of 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`. +1. Adds support for a `route_service_url` key in the binding response. + +## Dependencies ## + +v2.8 of the services API has been supported since: + +* [Final build 226](https://github.com/cloudfoundry/cf-release/tree/v226) of [cf-release](https://github.com/cloudfoundry/cf-release/) +* v2.44.0 of the Cloud Controller API +* CLI [v6.14.0](https://github.com/cloudfoundry/cli/releases/tag/v6.14.0) + +## API Overview ## + +The Cloud Foundry services API defines the contract between the Cloud +Controller and the service broker. +The broker is expected to implement several HTTP (or HTTPS) endpoints +underneath a URI prefix. +One or more services can be provided by a single broker, and load balancing +enables horizontal scalability of redundant brokers. +Multiple Cloud Foundry instances can be supported by a single broker using +different URL prefixes and credentials. + +<%= image_tag("../images/v2services-new.png", :width =>"960", :height =>"720", :style => 'background-color:#fff') %> + +## API Version Header ## + +Requests from the Cloud Controller to the broker contain a header that defines +the version number of the Broker API that Cloud Controller will use. +This header will be useful in future minor revisions of the API to allow +brokers to reject requests from Cloud Controllers that they do not understand. +While minor API revisions will always be additive, it is possible that brokers +will come to depend on a feature that was added after 2.0, so they may use this +header to reject the request. +Error messages from the broker in this situation should inform the operator of +what the required and actual version numbers are so that an operator can go +upgrade Cloud Controller and resolve the issue. +A broker should respond with a `412 Precondition Failed` message when rejecting +a request. + +The version numbers are in the format `MAJOR.MINOR`, using semantic versioning +such that 2.9 comes before 2.10. +An example of this header as of publication time is: + +`X-Broker-Api-Version: 2.8` + +## Authentication ## + +Cloud Controller (final release v145+) authenticates with the Broker using HTTP +basic authentication (the `Authorization:` header) on every request and will +reject any broker registrations that do not contain a username and password. +The broker is responsible for checking the username and password and returning +a `401 Unauthorized` message if credentials are invalid. +Cloud Controller supports connecting to a broker using SSL if additional +security is desired. + +## Catalog Management ## + +The first endpoint that a broker must implement is the service catalog. +Cloud Controller will initially fetch this endpoint from all brokers and make +adjustments to the user-facing service catalog stored in the Cloud Controller +database. +If the catalog fails to initially load or validate, Cloud Controller will not +allow the operator to add the new broker and will give a meaningful error +message. +Cloud Controller will also update the catalog whenever a broker is updated, so +you can use `update-service-broker` with no changes to force a catalog refresh. + +When Cloud Controller fetches a catalog from a broker, it will compare the +broker's id for services and plans with the `unique_id` values for services and +plans in the Cloud Controller database. +If a service or plan in the broker catalog has an id that is not present +amongst the `unique_id` values in the database, a new record will be added to +the database. +If services or plans in the database are found with `unique_id`s that match the +broker catalog's id, Cloud Controller will update the records to match +the broker’s catalog. + +If the database has plans which are not found in the broker catalog, and there +are no associated service instances, Cloud Controller will remove these plans +from the database. Cloud Controller will then delete services that do not have associated plans +from the database. +If the database has plans which are not found in the broker catalog, and there +**are** provisioned instances, the plan will be marked “inactive” and will +no longer be visible in the marketplace catalog or be provisionable. + + +### Request ### + +##### Route ##### +`GET /v2/catalog` + +##### cURL ##### +
+ $ curl -H "X-Broker-API-Version: 2.8" http://username:password@broker-url/v2/catalog
+
+ +### Response ### + + + + + + + + + + + + + + +
Status CodeDescription
200 OKThe expected response body is below.
+ +##### Body ##### + +CLI and web clients have different needs with regard to service and plan names. +A CLI-friendly string is all lowercase, with no spaces. +Keep it short -- imagine a user having to type it as an argument for a longer +command. +A web-friendly display name is camel-cased with spaces and punctuation supported. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Response fieldTypeDescription
services*array-of-objectsSchema of service objects defined below:
   id*stringAn identifier used to correlate this service in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended.
   name*stringThe CLI-friendly name of the service that will appear in the catalog. All lowercase, no spaces.
   description*stringA short description of the service that will appear in the catalog.
   bindable*booleanWhether the service can be bound to applications.
   tagsarray-of-stringsTags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp.
   metadataobjectA list of metadata for a service offering. For more information, see Service Metadata.
   requiresarray-of-stringsA list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are syslog_drain and route_forwarding; for more info see Application Log Streaming and Route Services.
   plan_updateableboolean + Whether the service supports upgrade/downgrade for some plans. +
+ Please note that the misspelling of the attribute plan_updatable to plan_updateable was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility. +
   plans*array-of-objects +A list of plans for this service, schema defined below:
      id*stringAn identifier used to correlate this plan in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended.
      name*stringThe CLI-friendly name of the plan that will appear in the catalog. All lowercase, no spaces.
      description*stringA short description of the service that will appear in the catalog.
      metadataobjectA list of metadata for a service plan. For more information, see Service Metadata.
      freebooleanThis field allows the plan to be limited by the non_basic_services_allowed field in a Cloud Foundry Quota, see Quota Plans. Default: true
   dashboard_clientobjectContains the data necessary to activate the Dashboard SSO feature for this service
      idstringThe id of the Oauth2 client that the service intends to use. The name may be taken, in which case the API will return an error to the operator
      secretstringA secret for the dashboard client
      redirect_uristringA domain for the service dashboard that will be whitelisted by the UAA to enable SSO
+ +\* Fields with an asterisk are required. + +
+{
+  "services": [{
+    "id": "service-guid-here",
+    "name": "mysql",
+    "description": "A MySQL-compatible relational database",
+    "bindable": true,
+    "plans": [{
+      "id": "plan1-guid-here",
+      "name": "small",
+      "description": "A small shared database with 100mb storage quota and 10 connections"
+    },{
+      "id": "plan2-guid-here",
+      "name": "large",
+      "description": "A large dedicated database with 10GB storage quota, 512MB of RAM, and 100 connections",
+      "free": false
+    }],
+    "dashboard_client": {
+      "id": "client-id-1",
+      "secret": "secret-1",
+      "redirect_uri": "https://dashboard.service.com"
+    }
+  }]
+}
+
+ +### Adding a Broker to Cloud Foundry ### + +Once you've implemented the first endpoint `GET /v2/catalog` above, you'll want +to [register the broker with CF](managing-service-brokers.html#register-broker) +to make your services and plans available to end users. + +## Asynchronous Operations ## + +Previously, Cloud Foundry only supported synchronous integration with service brokers. Brokers must return a valid response within 60 seconds and if the response is `201 CREATED`, users expect a service instance to be usable. This limits the services brokers can offer to those that can be provisioned in 60 seconds; brokers could return a success prematurely, but this leaves users wondering why their service instance is not usable and when it will be. + +With support for Asynchronous Operations, brokers still must respond within 60 seconds but may now return a `202 ACCEPTED`, indicating that the requested operation has been accepted but is not complete. This triggers Cloud Foundry to poll a new endpoint `/v2/service_instances/:guid/last_operation` until the broker indicates that the requested operation has succeeded or failed. During the intervening time, end users are able to discover the state of the requested operation using Cloud Foundry API clients such as the CLI. + +For an operation to be executed asynchronously, all three components (CF API client, CF, and broker) must support the feature. The parameter `accepts_incomplete=true` must be passed in a request by the CF API client, triggering CF to include the same parameter in a request to the broker. The broker can then choose to execute the request synchronously or asynchronously. + +If the broker executes the request asynchronously, the response must use the status code `202 ACCEPTED`; the response body should be the same as if the broker were serving the request synchronously. + +

Note: Asynchronous Operations are currently supported only for provision, update, and deprovision. Bind and unbind will be added once the feature is considered stable.

+ +If the `accepts_incomplete=true` parameter is not included, and the broker cannot fulfill the request synchronously (guaranteeing that the operation is complete on response), then the broker should reject the request with the status code `422 UNPROCESSABLE ENTITY` and the following body: + +
+{
+  "error": "AsyncRequired",
+  "description": "This service plan requires client support for asynchronous service operations."
+}
+
+ +To execute a request synchronously, the broker need only return the usual status codes; `201 CREATED` for create, and `200 OK` for update and delete. + +### Sequence Diagram ### + + <%= image_tag("images/async-service-broker-flow.png", :width =>"1250", :height =>"823", :style => 'background-color:#fff') %> + + +### Blocking Operations ### + +The Cloud Controller ensures that service brokers do not receive requests for an instance while an asynchronous operation is in progress. For example, if a broker is in the process of provisioning an instance asynchronously, the Cloud Controller will not allow any update, bind, unbind, or deprovision requests to be made through the platform. A user who attempts to perform one of these actions while an operation is already in progress will get an HTTP 400 with error message "Another operation for this service instance is in progress." + +### When to use Asynchronous Service Operations ### + +Service brokers should respond to all Cloud Controller requests within 60 seconds. Brokers that can guarantee completion of the requested operation with the response may return the synchronous response (e.g. `201 CREATED` for a provision request). Brokers that cannot guarantee completion of the operation with the response should implement support for asynchronous provisioning. Support for synchronous or asynchronous responses may vary by service offering, even by service plan. + +## Polling Last Operation (async only) ## + +When a broker returns status code `202 ACCEPTED` for [provision](#provisioning), [update](#updating_service_instance), or [deprovision](#deprovisioning), Cloud Foundry will begin to poll the `/v2/service_instances/:guid/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`. + +Valid values for `state` are `in progress`, `succeeded`, and `failed`. Cloud Foundry will poll the `last_operation` endpoint as long as the broker returns `"state": "in progress"`. Returning `"state": "succeeded"` or `"state": "failed"` will cause Cloud Foundry to cease polling. The value provided for `description` will be passed through to the CF API client and can be used to provide additional detail for users about the state of the operation. + +### Request ### + +##### Route ##### +`GET /v2/service_instances/:instance_id/last_operation` + +##### cURL ##### +
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
+
+ +### Response ### + + + + + + + + + + + + + + + + + + +
Status CodeDescription
200 OKThe expected response body is below.
410 GONEAppropriate only for asynchronous delete requests. Cloud Foundry will consider this response a success and remove the resource from its database. The expected response body is {}. Returning this while Cloud Foundry is polling for create or update operations will be interpreted as an invalid response and Cloud Foundry will continue polling.
+ +Responses with any other status code will be interpreted as an error or invalid response; Cloud Foundry will continue polling until the broker returns a valid response or the [maximum polling duration](#max-polling-duration) is reached. Brokers may use the `description` field to expose user-facing error messages about the operation state; for more info see [Broker Errors](api.html#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For success responses, the following fields are valid. + + + + + + + + + + + + + + + + + + + + + +
Response fieldTypeDescription
state*stringValid values are in progress, succeeded, and failed. While "state": "in progress", Cloud Foundry will continue polling. A response with "state": "succeeded" or "state": "failed" will cause Cloud Foundry to cease polling.
descriptionstringOptional field. A user-facing message displayed to the Cloud Foundry API client. Can be used to tell the user details about the status of the operation.
+ +
+{
+  "state": "in progress",
+  "description": "Creating service (10% complete)."
+}
+
+ +### Polling Interval ### +When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state at a configured interval. The Cloud Foundry operator can configure this interval in the BOSH deployment manifest using the property `properties.cc.broker_client_default_async_poll_interval_seconds` (defaults to 60 seconds). The maximum supported polling interval is 86400 seconds (24 hours). + +### Maximum Polling Duration ### +When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state until the broker response includes `"state":"succeeded"` or `"state":"failed"`, or until a maximum polling duration is reached. If the max polling duration is reached, Cloud Foundry will cease polling and the operation state will be considered `failed`. The Cloud Foundry operator can configure this max polling duration in the BOSH deployment manifest using the property `properties.cc.broker_client_max_async_poll_duration_minutes` (defaults to 10080 minutes or 1 week). + +### Additional Resources ### + +* An example broker that implements this feature can be found at [Example Service Brokers](examples.html). +* A demo video of the CLI user experience using the above broker can be found [here](https://youtu.be/Ij5KSKrAq9Q). + +## Provisioning ## + +When the broker receives a provision request from Cloud Controller, it should +synchronously take whatever action is necessary to create a new service +resource for the developer. +The result of provisioning varies by service type, although there are a few +common actions that work for many services. +For a MySQL service, provisioning could result in: + +* An empty dedicated `mysqld` process running on its own VM. +* An empty dedicated `mysqld` process running in a lightweight container on a +shared VM. +* An empty dedicated `mysqld` process running on a shared VM. +* An empty dedicated database, on an existing shared running `mysqld`. +* A database with business schema already there. +* A copy of a full database, for example a QA database that is a copy of the +production database. + +For non-data services, provisioning could just mean getting an account on an +existing system. + +### Request ### + +##### Route ##### +`PUT /v2/service_instances/:instance_id` + +

Note: The :instance_id of a service instance is provided by the Cloud Controller. This ID will be used for future requests (bind and deprovision), so the broker must use it to correlate the resource it creates.

+ +##### Body ##### + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Request fieldTypeDescription
organization_guid*stringThe Cloud Controller GUID of the organization under which the service is to be provisioned. Although most brokers will not use this field, it could be helpful in determining data placement or applying custom business rules.
plan_id*stringThe ID of the plan within the above service (from the catalog endpoint) that the user would like provisioned. Because plans have identifiers unique to a broker, this is enough information to determine what to provision.
service_id*stringThe ID of the service within the catalog above. While not strictly necessary, some brokers might make use of this ID.
space_guid*stringSimilar to organization_guid, but for the space.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous provisioning. If this parameter is not included in the request, and the broker can only provision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.
+ +
+{
+  "organization_guid": "org-guid-here",
+  "plan_id":           "plan-guid-here",
+  "service_id":        "service-guid-here",
+  "space_guid":        "space-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  }
+}
+
+ +##### cURL ##### +
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
+  "organization_guid": "org-guid-here",
+  "plan_id":           "plan-guid-here",
+  "service_id":        "service-guid-here",
+  "space_guid":        "space-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  }
+}' -X PUT -H "X-Broker-API-Version: 2.8" -H "Content-Type: application/json"
+
+ +In this case, `instance_id` refers to the service instance id generated by Cloud +Controller + +### Response ### + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription
201 CreatedService instance has been created. The expected response body is below.
200 OK + May be returned if the service instance already exists and the requested parameters are identical to the existing service instance. + The expected response body is below. +
202 AcceptedService instance creation is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
409 ConflictShould be returned if the requested service instance already exists. The expected response body is {}.
422 Unprocessable EntityShould be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.
+ +Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors). + + + + + + + + + + + + + + + + +
Response fieldTypeDescription
dashboard_urlstringThe URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL should contain enough information for the dashboard to identify the resource being accessed ("9189kdfsk0vfnku" in the example below). For information on how users can authenticate with service dashboards via SSO, see Dashboard Single Sign-On.
+ +
+{
+ "dashboard_url": "http://example-dashboard.com/9189kdfsk0vfnku"
+}
+
+ + +## Updating a Service Instance ## + +Brokers that implement this endpoint can enable users to modify attributes of an existing service instance. The first attribute Cloud Foundry supports users modifying is the service plan. This effectively enables users to upgrade or downgrade their service instance to other plans. To see how users make these requests, see [Managing Services](../devguide/services/managing-services.html#update_service). + +To enable this functionality, a broker declares support for each service by including `plan_updateable: true` in its [catalog endpoint](#catalog-mgmt). If this optional field is not included, Cloud Foundry will return a meaningful error to users for any plan change request, and will not make an API call to the broker. If this field is included and configured as true, Cloud Foundry will make API calls to the broker for all plan change requests, and it is up to the broker to validate whether a particular permutation of plan change is supported. Not all permutations of plan changes are expected to be supported. For example, a service may support upgrading from plan "shared small" to "shared large" but not to plan "dedicated". If a particular plan change is not supported, the broker should return a meaningful error message in response. + +### Request ### + +##### Route ##### +`PATCH /v2/service_instances/:instance_id` + +

Note: :instance_id is the global unique ID of a previously-provisioned service instance.

+ +##### Body ##### + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Request FieldTypeDescription
service_id*stringThe ID of the service within the catalog above. While not strictly necessary, some brokers might make use of this ID.
plan_idstringID of the new plan from the catalog.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
previous_valuesobjectInformation about the instance prior to the update.
previous_values.plan_idstringID of the plan prior to the update.
previous_values.service_idstringID of the service for the instance.
previous_values.organization_idstringID of the organization containing the instance.
previous_values.space_idstringID of the space containing the instance..
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous update. If this parameter is not included in the request, and the broker can only update an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.
+ +
+{
+  "service_id": "service-guid-here",
+  "plan_id": "plan-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  },
+  "previous_values": {
+    "plan_id": "old-plan-guid-here",
+    "service_id": "service-guid-here",
+    "organization_id": "org-guid-here",
+    "space_id": "space-guid-here"
+  }
+}
+
+ +##### cURL ##### +
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
+  "service_id": "service-guid-here",
+  "plan_id": "plan-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  },
+  "previous_values": {
+    "plan_id": "old-plan-guid-here",
+    "service_id": "service-guid-here",
+    "organization_id": "org-guid-here",
+    "space_id": "space-guid-here"
+  }
+}' -X PATCH -H "X-Broker-API-Version: 2.8" -H "Content-Type: application/json"
+
+ +### Response ### + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription
200 OKNew plan is effective. The expected response body is {}.
202 AcceptedService instance update is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
422 Unprocessable entity + May be returned if the particular plan change requested is not supported or if the request cannot currently be fulfilled due to the state of the instance (eg. instance utilization is over the quota of the requested plan). Broker should include a user-facing message in the body; for details see Broker Errors. Additionally, a 422 can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }. +
+ +Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For a success response, the expected response body is `{}`. + +## Binding ## + +

Note: Not all services must be bindable --- some deliver value just from being provisioned. Brokers that offer services that are bindable should declare them as such using bindable: true in the Catalog. Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

+ +### Types of Binding ### + +#### Credentials #### + +Credentials are a set of information used by an application or a user to utilize the service instance. If `bindable:true` is declared for a service in the catalog endpoint, users may request generation of credentials either by binding the service instance to an application or by creating a service key. When a service instance is bound to an app, Cloud Foundry will send the app id with the request. When a service key is created, the app id is not included. If the broker supports generation of credentials it should return `credentials` in the response. Credentials should be unique whenever possible, so access can be revoked for one application or user without affecting another. For more information on credentials, see [Binding Credentials](binding-credentials.html). + +#### Application Log Streaming #### + +In response to a bind request for an application (`app_id` included), a broker may also enable streaming of application logs from Cloud Foundry to a consuming service instance by returning `syslog_drain_url`. For details, see [Application Log Streaming](app-log-streaming.html). + +#### Route Services #### + +If a broker has declared `"requires":["route_forwarding"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind a service to a route. When bound to a route, the route itself will be sent with the bind request. A route is an address used by clients to reach apps mapped to the route. In response a broker may return a `route_service_url` which Cloud Foundry will use to proxy any request for the route to the service instance at URL specified by `route_service_url`. A broker may declare `"requires":["route_forwarding"]` but not return `route_service_url`; this enables a broker to dynamically configure a network component already in the request path for the route, requiring no change in the Cloud Foundry router. For more information, see [Route Services](route-services.html). + +### Request ### + +##### Route ##### +`PUT /v2/service_instances/:instance_id/service_bindings/:binding_id` + +

Note: The :binding_id of a service binding is provided by the Cloud Controller. +:instance_id is the ID of a previously-provisioned service instance; :binding_id +will be used for future unbind requests, so the broker must use it to correlate +the resource it creates.

+ +##### Body ##### + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Request FieldTypeDescription
service_id*stringID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id*stringID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
app_guidstringGUID of the application that you want to bind your service to. Will be included when users bind applications to service instances.
bind_resourceJSON objectA JSON object that contains the required fields of the resource being bound. Currently only app_guid for application bindings and route for route bindings are supported.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
+ +
+{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "app_guid":     "app-guid-here",
+  "bind_resource":     {
+    "app_guid": "app-guid-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}
+
+ +
+{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "bind_resource":     {
+    "route": "route-url-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}
+
+ +##### cURL ##### +
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "app_guid":     "app-guid-here",
+  "bind_resource":     {
+    "app_guid": "app-guid-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}' -X PUT
+
+ +
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "bind_resource":     {
+    "route": "route-url-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}' -X PUT
+
+ +In this case, `instance_id` refers to the id of an existing service instance in a previous provisioning, while `binding_id` is service binding id generated by Cloud Controller. + +### Response ### + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription
201 CreatedBinding has been created. The expected response body is below.
200 OK + May be returned if the binding already exists and the requested parameters are identical to the existing binding. + The expected response body is below. +
409 ConflictShould be returned if the requested binding already exists. The expected response body is {}, though the description field can be used to return a user-facing error message, as described in Broker Errors.
422 Unprocessable EntityShould be returned if the broker requires that app_guid be included in the request body. The expected response body is: { "error": "RequiresApp", "description": "This service supports generation of credentials through binding an application only." }
+ +Responses with any other status code will be interpreted as a failure and an unbind request will be sent to the broker to prevent an orphan being created on the broker. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors). + + + + + + + + + + + + + + + + + + + + + + + + + + +
Response FieldTypeDescription
credentialsobjectA free-form hash of credentials that the bound application can use to access the service. For more information, see Binding Credentials.
syslog_drain_urlstringA URL to which Cloud Foundry should drain logs for the bound application. requires:syslog_drain must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Application Log Streaming.
route_service_urlstringA URL to which Cloud Foundry should proxy requests for the bound route. requires:route_forwarding must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Route Services.
+ +
+	{
+	  "credentials": {
+	    "uri": "mysql://mysqluser:pass@mysqlhost:3306/dbname",
+	    "username": "mysqluser",
+	    "password": "pass",
+	    "host": "mysqlhost",
+	    "port": 3306,
+	    "database": "dbname"
+	  }
+	}
+
+ +## Unbinding ## + +

Note: Brokers that do not provide any bindable services do not need to implement the endpoint for unbind requests.

+ +When a broker receives an unbind request from Cloud Controller, it should +delete any resources it created in bind. +Usually this means that an application immediately cannot access the resource. + +### Request ### + +##### Route ##### +`DELETE /v2/service_instances/:instance_id/service_bindings/:binding_id` + +The `:binding_id` in the URL is the identifier of a previously created binding (the same `:binding_id` passed in the bind request). The request has no body, because DELETE requests generally do not have bodies. + +##### Parameters ##### + +The request provides these query string parameters as useful hints for brokers. + + + + + + + + + + + + + + + + + + + + + +
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id*stringID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
+ +##### cURL ##### +
+$ curl 'http://username:password@broker-url/v2/service_instances/:instance_id/
+  service_bindings/:binding_id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.8"
+
+ +### Response ### + + + + + + + + + + + + + + + + + + +
Status CodeDescription
200 OKBinding was deleted. The expected response body is {}.
410 GoneShould be returned if the binding does not exist. The expected response body is {}.
+ +Responses with any other status code will be interpreted as a failure and the binding will remain in the Cloud Controller database. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For a success response, the expected response body is `{}`. + +## Deprovisioning ## + +When a broker receives a deprovision request from Cloud Controller, it should +delete any resources it created during the provision. +Usually this means that all resources are immediately reclaimed for future +provisions. + +### Request ### + +##### Route ##### +`DELETE /v2/service_instances/:instance_id` + +The `:instance_id` in the URL is the identifier of a previously provisioned instance (the same +`:instance_id` passed in the provision request). The request has no body, because DELETE +requests generally do not have bodies. + +##### Parameters ##### + +The request provides these query string parameters as useful hints for brokers. + + + + + + + + + + + + + + + + + + + + + + + + + + +
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id*stringID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the broker can only deprovision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.
+ +##### cURL ##### +
+$ curl 'http://username:password@broker-url/v2/service_instances/:instance_id?service_id=
+    service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.8"
+
+ +### Response ### + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status CodeDescription
200 OKService instance was deleted. The expected response body is {}.
202 AcceptedService instance deletion is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
410 GoneShould be returned if the service instance does not exist. The expected response body is {}.
422 Unprocessable EntityShould be returned if the broker only supports asynchronous deprovisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.
+ +Responses with any other status code will be interpreted as a failure and the service instance will remain in the Cloud Controller database. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For a success response, the expected response body is `{}`. + +## Broker Errors ## + +### Response ### + +Broker failures beyond the scope of the well-defined HTTP response codes listed +above (like 410 on delete) should return an appropriate HTTP response code +(chosen to accurately reflect the nature of the failure) and a body containing a valid JSON Object (not an array). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For error responses, the following fields are valid. Others will be ignored. If an empty JSON object is returned in the body `{}`, a generic message containing the HTTP response code returned by the broker will be displayed to the requestor. + + + + + + + + + + + + + + + + +
Response FieldTypeDescription
descriptionstringAn error message explaining why the request failed. This message will be displayed to the user who initiated the request. +
+ +
+{
+  "description": "Something went wrong. Please contact support at http://support.example.com."
+}
+
+ +## Orphans ## + +The Cloud Controller is the source of truth for service instances and bindings. Service brokers are expected to have successfully provisioned all the instances and bindings Cloud Controller knows about, and none that it doesn't. + +Orphans can result if the broker does not return a response before a request from Cloud Controller times out (typically 60 seconds). For example, if a broker does not return a response to a provision request before Cloud Controller times out, the broker might eventually succeed in provisioning an instance after Cloud Controller considers the request a failure. This results in an orphan instance on the service side. + +To mitigate orphan instances and bindings, Cloud Controller will attempt to delete resources it cannot be sure were successfully created, and will keep trying to delete them until the broker responds with a success. + +More specifically, when a provision or bind request to the broker fails, Cloud Controller will immediately send a corresponding delete or unbind request. If the delete or unbind request fails, Cloud Controller will retry the delete or unbind request ten times with an exponental backoff schedule (over a period of 34 hours). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status codeResultOrphan mitigation
200Success
200 with malformed responseFailure
201Success
201 with malformed responseFailureYes
All other 2xxFailureYes
408Failure due to timeoutYes
All other 4xxBroker rejects request
5xxBroker errorYes
TimeoutFailureYes
+ +If the Cloud Controller encounters an internal error provisioning an instance or binding (for example, saving to the database fails), then the Cloud Controller will send a single delete or unbind request to the broker but will not retry. + +This orphan mitigation behavior was introduced in cf-release v196. diff --git a/api.html.md.erb b/api.html.md.erb index 7e98581..7046db1 100644 --- a/api.html.md.erb +++ b/api.html.md.erb @@ -1,5 +1,5 @@ --- -title: Service Broker API v2.8 +title: Service Broker API v2.9 owner: Services API --- @@ -22,18 +22,16 @@ added to enable support for new features. These fields must be optional and should be ignored by clients and servers that do not understand them. -### Changes Since v2.7 ### +### Changes Since v2.8 ### -1. Brokers may now include a requires: ["route_forwarding"] on their catalog endpoint. -1. On bind, the Cloud Controller will now send a new top-level key, `bind_resource`, under which the required parameters of 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`. -1. Adds support for a `route_service_url` key in the binding response. +1. Querying `last_operation` now supports `service_id` and `plan_id` query parameters. ## Dependencies ## -v2.8 of the services API has been supported since: +v2.9 of the services API has been supported since: -* [Final build 226](https://github.com/cloudfoundry/cf-release/tree/v226) of [cf-release](https://github.com/cloudfoundry/cf-release/) -* v2.44.0 of the Cloud Controller API +* [Final build 238](https://github.com/cloudfoundry/cf-release/tree/v238) of [cf-release](https://github.com/cloudfoundry/cf-release/) +* v2.57.0 of the Cloud Controller API * CLI [v6.14.0](https://github.com/cloudfoundry/cli/releases/tag/v6.14.0) ## API Overview ## @@ -68,7 +66,7 @@ The version numbers are in the format `MAJOR.MINOR`, using semantic versioning such that 2.9 comes before 2.10. An example of this header as of publication time is: -`X-Broker-Api-Version: 2.8` +`X-Broker-Api-Version: 2.9` ## Authentication ## @@ -118,7 +116,7 @@ no longer be visible in the marketplace catalog or be provisionable. #### cURL #### 
- $ curl -H "X-Broker-API-Version: 2.8" http://username:password@broker-url/v2/catalog
+ $ curl -H "X-Broker-API-Version: 2.9" http://username:password@broker-url/v2/catalog
### Response ### @@ -428,6 +426,32 @@ Valid values for `state` are `in progress`, `succeeded`, and `failed`. Cloud Fou ##### Route ##### `GET /v2/service_instances/:instance_id/last_operation` +##### Parameters ##### + +The request provides these query string parameters as useful hints for brokers. + + + + + + + + + + + + + + + + + + + + + +
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id*stringID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
+ ##### cURL ##### 
 $ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
@@ -598,7 +622,7 @@ $ curl http://username:password@broker-url/v2/service_instances/:instance_id -d
     "parameter1": 1,
     "parameter2": "value"
   }
-}' -X PUT -H "X-Broker-API-Version: 2.8" -H "Content-Type: application/json"
+}' -X PUT -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
In this case, `instance_id` refers to the service instance id generated by Cloud @@ -776,7 +800,7 @@ $ curl http://username:password@broker-url/v2/service_instances/:instance_id -d "organization_id": "org-guid-here", "space_id": "space-guid-here" } -}' -X PATCH -H "X-Broker-API-Version: 2.8" -H "Content-Type: application/json" +}' -X PATCH -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json" ### Response ### @@ -1053,20 +1077,22 @@ The request provides these query string parameters as useful hints for brokers. service_id* string - ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID. + ID of the service from the catalog. plan_id* string - ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID. + ID of the plan from the catalog. +\* Query parameters with an asterisk are required. + ##### cURL ##### 
 $ curl 'http://username:password@broker-url/v2/service_instances/:instance_id/
-  service_bindings/:binding_id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.8"
+  service_bindings/:binding_id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.9"
### Response ### @@ -1145,10 +1171,12 @@ The request provides these query string parameters as useful hints for brokers. +\* Query parameters with an asterisk are required. + ##### cURL ##### 
 $ curl 'http://username:password@broker-url/v2/service_instances/:instance_id?service_id=
-    service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.8"
+    service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.9"
### Response ### From e299fe98bb69a3380514f38811ff19d121249190 Mon Sep 17 00:00:00 2001 From: Eric Saxby Date: Fri, 20 May 2016 12:24:07 -0700 Subject: [PATCH 2/6] Clarify mandatory fields and params Signed-off-by: Stev Witzel --- api.html.md.erb | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/api.html.md.erb b/api.html.md.erb index 7046db1..fc892f6 100644 --- a/api.html.md.erb +++ b/api.html.md.erb @@ -442,16 +442,18 @@ The request provides these query string parameters as useful hints for brokers. service_id* string - ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID. + ID of the service from the catalog. plan_id* string - ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID. + ID of the plan from the catalog. +\* Query parameters with an asterisk are required. + ##### cURL ##### 
 $ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
@@ -508,6 +510,8 @@ For success responses, the following fields are valid.
 
 
 
+\* Fields with an asterisk are required.
+
 
 {
   "state": "in progress",
@@ -578,7 +582,7 @@ existing system.
 
   service_id*
   string
-  The ID of the service within the catalog above. While not strictly necessary, some brokers might make use of this ID.
+  The ID of the service within the catalog above.
 
 
   space_guid*
@@ -598,6 +602,8 @@ existing system.
 
 
 
+\* Fields with an asterisk are required.
+
 
 {
   "organization_guid": "org-guid-here",
@@ -723,7 +729,7 @@ To enable this functionality, a broker declares support for each service by incl
 
   service_id*
   string
-  The ID of the service within the catalog above. While not strictly necessary, some brokers might make use of this ID.
+  The ID of the service within the catalog above.
 
 
   plan_id
@@ -768,6 +774,8 @@ To enable this functionality, a broker declares support for each service by incl
 
 
 
+\* Fields with an asterisk are required.
+
 
 {
   "service_id": "service-guid-here",
@@ -880,12 +888,12 @@ the resource it creates.

 
   service_id*
   string
-  ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
+  ID of the service from the catalog.
 
 
   plan_id*
   string
-  ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
+  ID of the plan from the catalog.
 
 
   app_guid
@@ -905,6 +913,8 @@ the resource it creates.

 
 
 
+\* Fields with an asterisk are required.
+
 
 {
   "plan_id":      "plan-guid-here",
@@ -1156,12 +1166,12 @@ The request provides these query string parameters as useful hints for brokers.
 
   service_id*
   string
-  ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID. 
+  ID of the service from the catalog.
 
 
   plan_id*
   string
-  ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
+  ID of the plan from the catalog.
 
 
   accepts_incomplete

From f6d5dbfed63ff0f2d6083faca59eb895182485a1 Mon Sep 17 00:00:00 2001
From: Paul Warren 
Date: Fri, 3 Jun 2016 12:33:18 -0700
Subject: [PATCH 3/6] Initial draft of volume services docs
 [#120378527](https://www.pivotaltracker.com/story/show/120378527)

---
 api.html.md.erb             |  11 +++-
 volume-services.html.md.erb | 107 ++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 volume-services.html.md.erb

diff --git a/api.html.md.erb b/api.html.md.erb
index fc892f6..76ee847 100644
--- a/api.html.md.erb
+++ b/api.html.md.erb
@@ -195,7 +195,7 @@ A web-friendly display name is camel-cased with spaces and punctuation supported
 
      requires
   array-of-strings
-  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 and route_forwarding; for more info see Application Log Streaming and Route Services.
+  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; for more info see Application Log Streaming, Route Services and Volume Services.
 
      max_db_per_node:
   strings
@@ -864,6 +864,10 @@ In response to a bind request for an application (`app_id` included), a broker m
 
 If a broker has declared `"requires":["route_forwarding"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind a service to a route. When bound to a route, the route itself will be sent with the bind request. A route is an address used by clients to reach apps mapped to the route. In response a broker may return a `route_service_url` which Cloud Foundry will use to proxy any request for the route to the service instance at URL specified by `route_service_url`. A broker may declare `"requires":["route_forwarding"]` but not return `route_service_url`; this enables a broker to dynamically configure a network component already in the request path for the route, requiring no change in the Cloud Foundry router. For more information, see [Route Services](route-services.html).
 
+#### Volume Services (Experimental)####
+
+If a broker has declared `"requires":["volume_mount"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind one or more volumes to an application.  In response to a bind request a volume service broker should return a set of `volume_mount` instructions that Cloud Foundry will ensure are mounted into the application's containers.  For more information, see [Volume Services](volume-services.html)
+
 ### Request ###
 
 ##### Route #####
@@ -1040,6 +1044,11 @@ For success responses, the following fields are supported. Others will be ignore
   string
   A URL to which Cloud Foundry should proxy requests for the bound route. requires:route_forwarding must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Route Services.
 
+
+  volume_mounts
+  array-of-objects
+  An array of volume mount instructions.  requires:volume_mount must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid.  For more information, see Volume Services
+
 
 
 
diff --git a/volume-services.html.md.erb b/volume-services.html.md.erb
new file mode 100644
index 0000000..a178748
--- /dev/null
+++ b/volume-services.html.md.erb
@@ -0,0 +1,107 @@
+---
+title: Volume Services (Experimental)
+owner: Core Services
+---
+
+<%= modified_date %>
+
+## Introduction ##
+
+Cloud Foundry application developers may wish to have their applications mount one or more volumes in order to be able to write to a reliable (rather than ephemeral) file system.  Through integrations with service brokers and with the Cloud Foundry runtime, providers can offer these services to developers with a familiar automated, self-service, and on-demand user experience.
+
+This feature is EXPERIMENTAL.
+
+## Schema ##
+
+### Service Broker Bind Response ###
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
FieldTypeDescription
volume_mounts*volume_mount[]An array of volume_mount JSON objects

+
+### volume_mount ###
+
+ 
+ 
+   
+   
+   
+ 
+ 
+ 
+ 
+   
+   
+   
+ 
+ 
+   
+   
+   
+ 
+ 
+   
+   
+   
+ 
+ 
+ 
FieldTypeDescription
container_pathstringThe path to mount inside the application container
modestringIndicates whether the volume should be read-only or read-write
privateprivateA private JSON object

+
+### private ###
+
+ 
+ 
+   
+   
+   
+ 
+ 
+ 
+ 
+   
+   
+   
+ 
+ 
+   
+   
+   
+ 
+ 
+   
+   
+   
+ 
+ 
+ 
FieldTypeDescription
driverstringThe path to mount inside the application container
group_idstringIndicates whether the volume should be read-only or read-write
configobjectAn broker/driver specific JSON object.  The broker is free to return any valid JSON object here and it will be passed through the volume driver identified in the 'driver' field

+
+### Example ###
+
+	{
+	  ...
+	  "volume_mounts": {
+	    "container_path": "/data/images",
+	    "mode": "r",
+	    "private": {
+	      "driver": "cephdriver",
+	      "group_id": "bc2c1eab-05b9-482d-b0cf-750ee07de311",
+	      "config": {
+	        "remote_mount_point": "/mnt/bc2c1eab-05b9-482d-b0cf-750ee07de311"
+	      }
+	    }
+	  }
+	}
+


From 2603ce5beb6189f48f77e072faf7d0714796d224 Mon Sep 17 00:00:00 2001
From: Alex Ley 
Date: Tue, 14 Jun 2016 14:20:23 +0100
Subject: [PATCH 4/6] add details of 'operation' param support for async
 operations for v2.9 of the API

---
 api.html.md.erb | 72 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 68 insertions(+), 4 deletions(-)

diff --git a/api.html.md.erb b/api.html.md.erb
index 76ee847..cb83a0d 100644
--- a/api.html.md.erb
+++ b/api.html.md.erb
@@ -25,6 +25,8 @@ that do not understand them.
 ### Changes Since v2.8 ###
 
 1. Querying `last_operation` now supports `service_id` and `plan_id` query parameters.
+1. Provision, Update, Deprovision responses now accepts an optional `operation` json param for async responses. This is used to by service brokers to return an state related to the operation. Provided back to the service broker via the `last_operation` call.
+1. Querying `last_operation` now supports `operation` param back to the service broker.
 
 ## Dependencies ##
 
@@ -449,6 +451,11 @@ The request provides these query string parameters as useful hints for brokers.
   string
   ID of the plan from the catalog.
 
+
+  operation
+  string
+  The field optionally returned by the service broker on Provision, Update, Deprovision asyn responses. Repesents any state the service broker responsed with as a URL encoded string..
+
 
 
 
@@ -692,12 +699,18 @@ For success responses, the following fields are supported. Others will be ignore
   string
   The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL should contain enough information for the dashboard to identify the resource being accessed ("9189kdfsk0vfnku" in the example below). For information on how users can authenticate with service dashboards via SSO, see Dashboard Single Sign-On.
 
+
+  operation
+  string
+  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_opertion` requests as a URL encoded query param..
+
 
 
-
+\* Fields with an asterisk are required.
 
 {
- "dashboard_url": "http://example-dashboard.com/9189kdfsk0vfnku"
+ "dashboard_url": "http://example-dashboard.com/9189kdfsk0vfnku",
+ "operation": "task_10"
 }
 

 
@@ -844,7 +857,31 @@ Responses with any other status code will be interpreted as a failure. Brokers c
 
 All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
 
-For a success response, the expected response body is `{}`.
+For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_opertion` requests as a URL encoded query param..

+\* Fields with an asterisk are required.
+
+{
+ "operation": "task_10"
+}
+

+
 
 ## Binding ##
 
@@ -1139,9 +1176,36 @@ Responses with any other status code will be interpreted as a failure and the bi
 
 ##### Body #####
 
+Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
 All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
 
-For a success response, the expected response body is `{}`.
+For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_opertion` requests as a URL encoded query param..

+\* Fields with an asterisk are required.
+
+{
+ "operation": "task_10"
+}
+

 
 ## Deprovisioning ##
 

From 32f6b82e1e3e2fc3a550f91f4bcae1ac7fb8867b Mon Sep 17 00:00:00 2001
From: Alex Ley 
Date: Tue, 14 Jun 2016 14:51:49 +0100
Subject: [PATCH 5/6] fix typos

---
 api.html.md.erb | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/api.html.md.erb b/api.html.md.erb
index cb83a0d..bdc4f23 100644
--- a/api.html.md.erb
+++ b/api.html.md.erb
@@ -454,7 +454,7 @@ The request provides these query string parameters as useful hints for brokers.
 
   operation
   string
-  The field optionally returned by the service broker on Provision, Update, Deprovision asyn responses. Repesents any state the service broker responsed with as a URL encoded string..
+  The field optionally returned by the service broker on Provision, Update, Deprovision async responses. Repesents any state the service broker responsed with as a URL encoded string..
 
 
 
@@ -702,7 +702,7 @@ For success responses, the following fields are supported. Others will be ignore
 
   operation
   string
-  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_opertion` requests as a URL encoded query param..
+  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..
 
 
 
@@ -871,7 +871,7 @@ For success responses, the following fields are supported. Others will be ignore
 
   operation
   string
-  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_opertion` requests as a URL encoded query param..
+  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..
 
 
 
@@ -1196,7 +1196,7 @@ For success responses, the following fields are supported. Others will be ignore
 
   operation
   string
-  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_opertion` requests as a URL encoded query param..
+  For async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..
 
 
 

From b638d64f1e623446cc934ada3eb3cf133594a636 Mon Sep 17 00:00:00 2001
From: Eric Saxby 
Date: Thu, 16 Jun 2016 10:55:39 -0700
Subject: [PATCH 6/6] Current version of api page as symlink to version file

---
 api-v2.9.html.md.erb | 1409 +++++++++++++++++++++++++++++++++++++++++
 api.html.md.erb      | 1410 +-----------------------------------------
 2 files changed, 1410 insertions(+), 1409 deletions(-)
 create mode 100644 api-v2.9.html.md.erb
 mode change 100644 => 120000 api.html.md.erb

diff --git a/api-v2.9.html.md.erb b/api-v2.9.html.md.erb
new file mode 100644
index 0000000..bdc4f23
--- /dev/null
+++ b/api-v2.9.html.md.erb
@@ -0,0 +1,1409 @@
+---
+title: Service Broker API v2.9
+owner: Services API
+---
+
+<%= modified_date %>
+
+## Document Changelog ##
+
+[v2 API Change Log](v2-api-changelog.html)
+
+<%= partial "version_table.html" %>
+
+## Changes ##
+
+### Change Policy ###
+
+* Existing endpoints and fields will not be removed or renamed.
+* New optional endpoints, or new HTTP methods for existing endpoints, may be
+added to enable support for new features.
+* New fields may be added to existing request/response messages.
+These fields must be optional and should be ignored by clients and servers
+that do not understand them.
+
+### Changes Since v2.8 ###
+
+1. Querying `last_operation` now supports `service_id` and `plan_id` query parameters.
+1. Provision, Update, Deprovision responses now accepts an optional `operation` json param for async responses. This is used to by service brokers to return an state related to the operation. Provided back to the service broker via the `last_operation` call.
+1. Querying `last_operation` now supports `operation` param back to the service broker.
+
+## Dependencies ##
+
+v2.9 of the services API has been supported since:
+
+* [Final build 238](https://github.com/cloudfoundry/cf-release/tree/v238) of [cf-release](https://github.com/cloudfoundry/cf-release/)
+* v2.57.0 of the Cloud Controller API
+* CLI [v6.14.0](https://github.com/cloudfoundry/cli/releases/tag/v6.14.0)
+
+## API Overview ##
+
+The Cloud Foundry services API defines the contract between the Cloud
+Controller and the service broker.
+The broker is expected to implement several HTTP (or HTTPS) endpoints
+underneath a URI prefix.
+One or more services can be provided by a single broker, and load balancing
+enables horizontal scalability of redundant brokers.
+Multiple Cloud Foundry instances can be supported by a single broker using
+different URL prefixes and credentials.
+
+<%= image_tag("../images/v2services-new.png", :width =>"960", :height =>"720", :style => 'background-color:#fff') %>
+
+## API Version Header ##
+
+Requests from the Cloud Controller to the broker contain a header that defines
+the version number of the Broker API that Cloud Controller will use.
+This header will be useful in future minor revisions of the API to allow
+brokers to reject requests from Cloud Controllers that they do not understand.
+While minor API revisions will always be additive, it is possible that brokers
+will come to depend on a feature that was added after 2.0, so they may use this
+header to reject the request.
+Error messages from the broker in this situation should inform the operator of
+what the required and actual version numbers are so that an operator can go
+upgrade Cloud Controller and resolve the issue.
+A broker should respond with a `412 Precondition Failed` message when rejecting
+a request.
+
+The version numbers are in the format `MAJOR.MINOR`, using semantic versioning
+such that 2.9 comes before 2.10.
+An example of this header as of publication time is:
+
+`X-Broker-Api-Version: 2.9`
+
+## Authentication ##
+
+Cloud Controller (final release v145+) authenticates with the Broker using HTTP
+basic authentication (the `Authorization:` header) on every request and will
+reject any broker registrations that do not contain a username and password.
+The broker is responsible for checking the username and password and returning
+a `401 Unauthorized` message if credentials are invalid.
+Cloud Controller supports connecting to a broker using SSL if additional
+security is desired.
+
+## Catalog Management ##
+
+The first endpoint that a broker must implement is the service catalog.
+Cloud Controller will initially fetch this endpoint from all brokers and make
+adjustments to the user-facing service catalog stored in the Cloud Controller
+database.
+If the catalog fails to initially load or validate, Cloud Controller will not
+allow the operator to add the new broker and will give a meaningful error
+message.
+Cloud Controller will also update the catalog whenever a broker is updated, so
+you can use `update-service-broker` with no changes to force a catalog refresh.
+
+When Cloud Controller fetches a catalog from a broker, it will compare the
+broker's id for services and plans with the `unique_id` values for services and
+plans in the  Cloud Controller database.
+If a service or plan in the broker catalog has an id that is not present
+amongst the `unique_id` values in the database, a new record will be added to
+the database.
+If services or plans in the database are found with `unique_id`s that match the
+broker catalog's id, Cloud Controller will update the records to match
+the broker’s catalog.
+
+If the database has plans which are not found in the broker catalog, and there
+are no associated service instances, Cloud Controller will remove these plans
+from the database. Cloud Controller will then delete services that do not have associated plans
+from the database.
+If the database has plans which are not found in the broker catalog, and there
+**are** provisioned instances, the plan will be marked “inactive” and will
+no longer be visible in the marketplace catalog or be provisionable.
+
+
+### Request ###
+
+#### Route ####
+`GET /v2/catalog`
+
+#### cURL ####
+
+ $ curl -H "X-Broker-API-Version: 2.9" http://username:password@broker-url/v2/catalog
+

+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+
Status CodeDescription
200 OKThe expected response body is below.

+
+#### Body - Schema of Service Objects ####
+
+CLI and web clients have different needs with regard to service and plan names.
+A CLI-friendly string is all lowercase, with no spaces.
+Keep it short -- imagine a user having to type it as an argument for a longer
+command.
+A web-friendly display name is camel-cased with spaces and punctuation supported.
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
services*array-of-service-objectsSchema of service objects defined below.

+
+
 Service Objects 

+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+  
+  
+  
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
   name*stringThe CLI-friendly name of the service that will appear in the catalog. All lowercase, no spaces.
   id*stringAn identifier used to correlate this service in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended. 
   description*stringA short description of the service that will appear in the catalog.
   tagsarray-of-stringsTags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp.
   requiresarray-of-stringsA 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; for more info see Application Log Streaming, Route Services and Volume Services.
   max_db_per_node:strings
   bindable*booleanWhether the service can be bound to applications.
   metadataobjectA list of metadata for a service offering. For more information, see Service Metadata.
   dashboard_clientobjectContains the data necessary to activate the Dashboard SSO feature for this service
   plan_updateableboolean
+    Whether the service supports upgrade/downgrade for some plans.
+    

+    Please note that the misspelling of the attribute plan_updatable to plan_updateable was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility.
+  
   plans*array-of-objectsA list of plans for this service, schema is defined below.

+
+
 Dashboard Client Object  

+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
   idstringThe id of the Oauth2 client that the service intends to use. The name may be taken, in which case the updat will return an error to the operator
   secretstringA secret for the dashboard client
   redirect_uristringA domain for the service dashboard that will be whitelisted by the UAA to enable SSO

+
+
+
 Plan Object  

+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
   id*stringAn identifier used to correlate this plan in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended.
   name*stringThe CLI-friendly name of the plan that will appear in the catalog. All lowercase, no spaces.
   description*stringA short description of the service that will appear in the catalog.
   metadataobjectA list of metadata for a service plan. For more information, see Service Metadata.
   freebooleanThis field allows the plan to be limited by the non_basic_services_allowed field in a Cloud Foundry Quota, see Quota Plans. Default: true

+
+\* Fields with an asterisk are required.
+
+
+{
+  "services": [{
+    "name": "fake-service",
+    "id": "acb56d7c-XXXX-XXXX-XXXX-feb140a59a66",
+    "description": "fake service",
+    "tags": ["no-sql", "relational"],
+    "requires": ["route_forwarding"],
+    "max_db_per_node": 5,
+    "bindable": true,
+    "metadata": {
+      "provider": {
+        "name": "The name"
+      },
+      "listing": {
+        "imageUrl": "http://catgifpage.com/cat.gif",
+        "blurb": "Add a blurb here",
+        "longDescription": "A long time ago, in a galaxy far far away..."
+      },
+      "displayName": "The Fake Broker"
+    },
+    "dashboard_client": {
+      "id": "398e2f8e-XXXX-XXXX-XXXX-19a71ecbcf64",
+      "secret": "277cabb0-XXXX-XXXX-XXXX-7822c0a90e5d",
+      "redirect_uri": "http://localhost:1234"
+    },
+    "plan_updateable": true,
+    "plans": [{
+      "name": "fake-plan",
+      "id": "d3031751-XXXX-XXXX-XXXX-a42377d3320e",
+      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections",
+      "max_storage_tb": 5,
+      "metadata": {
+        "cost": 0,
+        "bullets": [{
+          "content": "Shared fake server"
+        }, {
+          "content": "5 TB storage"
+        }, {
+          "content": "40 concurrent connections"
+        }]
+      }
+    }, {
+      "name": "fake-async-plan",
+      "id": "0f4008b5-XXXX-XXXX-XXXX-dace631cd648",
+      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections. 100 async",
+      "max_storage_tb": 5,
+      "metadata": {
+        "cost": 0,
+        "bullets": [{
+          "content": "40 concurrent connections"
+        }]
+      }
+    }, {
+      "name": "fake-async-only-plan",
+      "id": "8d415f6a-XXXX-XXXX-XXXX-e61f3baa1c77",
+      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections. 100 async",
+      "max_storage_tb": 5,
+      "metadata": {
+        "cost": 0,
+        "bullets": [{
+          "content": "40 concurrent connections"
+        }]
+      }
+    }]
+  }]
+}
+

+
+
+### Adding a Broker to Cloud Foundry ###
+
+Once you've implemented the first endpoint `GET /v2/catalog` above, you'll want
+to [register the broker with CF](managing-service-brokers.html#register-broker)
+to make your services and plans available to end users.
+
+## Asynchronous Operations ##
+
+Previously, Cloud Foundry only supported synchronous integration with service brokers. Brokers must return a valid response within 60 seconds and if the response is `201 CREATED`, users expect a service instance to be usable. This limits the services brokers can offer to those that can be provisioned in 60 seconds; brokers could return a success prematurely, but this leaves users wondering why their service instance is not usable and when it will be.
+
+With support for Asynchronous Operations, brokers still must respond within 60 seconds but may now return a `202 ACCEPTED`, indicating that the requested operation has been accepted but is not complete. This triggers Cloud Foundry to poll a new endpoint `/v2/service_instances/:guid/last_operation` until the broker indicates that the requested operation has succeeded or failed. During the intervening time, end users are able to discover the state of the requested operation using Cloud Foundry API clients such as the CLI.
+
+For an operation to be executed asynchronously, all three components (CF API client, CF, and broker) must support the feature. The parameter `accepts_incomplete=true` must be passed in a request by the CF API client, triggering CF to include the same parameter in a request to the broker. The broker can then choose to execute the request synchronously or asynchronously.
+
+If the broker executes the request asynchronously, the response must use the status code `202 ACCEPTED`; the response body should be the same as if the broker were serving the request synchronously.
+
+
Note: Asynchronous Operations are currently supported only for provision, update, and deprovision. Bind and unbind will be added once the feature is considered stable.

+
+If the `accepts_incomplete=true` parameter is not included, and the broker cannot fulfill the request synchronously (guaranteeing that the operation is complete on response), then the broker should reject the request with the status code `422 UNPROCESSABLE ENTITY` and the following body:
+
+
+{
+  "error": "AsyncRequired",
+  "description": "This service plan requires client support for asynchronous service operations."
+}
+

+
+To execute a request synchronously, the broker need only return the usual status codes; `201 CREATED` for create, and `200 OK` for update and delete.
+
+### Sequence Diagram ###
+
+  <%= image_tag("images/async-service-broker-flow.png", :width =>"1250", :height =>"823", :style => 'background-color:#fff') %>
+
+
+### Blocking Operations ###
+
+The Cloud Controller ensures that service brokers do not receive requests for an instance while an asynchronous operation is in progress. For example, if a broker is in the process of provisioning an instance asynchronously, the Cloud Controller will not allow any update, bind, unbind, or deprovision requests to be made through the platform. A user who attempts to perform one of these actions while an operation is already in progress will get an HTTP 400 with error message "Another operation for this service instance is in progress."
+
+### When to use Asynchronous Service Operations ###
+
+Service brokers should respond to all Cloud Controller requests within 60 seconds. Brokers that can guarantee completion of the requested operation with the response may return the synchronous response (e.g. `201 CREATED` for a provision request). Brokers that cannot guarantee completion of the operation with the response should implement support for asynchronous provisioning. Support for synchronous or asynchronous responses may vary by service offering, even by service plan.
+
+## Polling Last Operation (async only) ##
+
+When a broker returns status code `202 ACCEPTED` for [provision](#provisioning), [update](#updating_service_instance), or [deprovision](#deprovisioning), Cloud Foundry will begin to poll the `/v2/service_instances/:guid/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`.
+
+Valid values for `state` are `in progress`, `succeeded`, and `failed`. Cloud Foundry will poll the `last_operation` endpoint as long as the broker returns `"state": "in progress"`. Returning `"state": "succeeded"` or `"state": "failed"` will cause Cloud Foundry to cease polling. The value provided for `description` will be passed through to the CF API client and can be used to provide additional detail for users about the state of the operation.
+
+### Request ###
+
+##### Route #####
+`GET /v2/service_instances/:instance_id/last_operation`
+
+##### Parameters #####
+
+The request provides these query string parameters as useful hints for brokers.
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.
operationstringThe field optionally returned by the service broker on Provision, Update, Deprovision async responses. Repesents any state the service broker responsed with as a URL encoded string..

+
+\* Query parameters with an asterisk are required.
+
+##### cURL #####
+
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
+

+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+  
+  
+
+
+
Status CodeDescription
200 OKThe expected response body is below.
410 GONEAppropriate only for asynchronous delete requests. Cloud Foundry will consider this response a success and remove the resource from its database. The expected response body is {}. Returning this while Cloud Foundry is polling for create or update operations will be interpreted as an invalid response and Cloud Foundry will continue polling.

+
+Responses with any other status code will be interpreted as an error or invalid response; Cloud Foundry will continue polling until the broker returns a valid response or the [maximum polling duration](#max-polling-duration) is reached. Brokers may use the `description` field to expose user-facing error messages about the operation state; for more info see [Broker Errors](api.html#broker-errors).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For success responses, the following fields are valid.
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
state*stringValid values are in progress, succeeded, and failed. While "state": "in progress", Cloud Foundry will continue polling. A response with "state": "succeeded" or "state": "failed" will cause Cloud Foundry to cease polling.
descriptionstringOptional field. A user-facing message displayed to the Cloud Foundry API client. Can be used to tell the user details about the status of the operation.

+
+\* Fields with an asterisk are required.
+
+
+{
+  "state": "in progress",
+  "description": "Creating service (10% complete)."
+}
+

+
+###  Polling Interval ###
+When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state at a configured interval. The Cloud Foundry operator can configure this interval in the BOSH deployment manifest using the property `properties.cc.broker_client_default_async_poll_interval_seconds` (defaults to 60 seconds). The maximum supported polling interval is 86400 seconds (24 hours).
+
+### Maximum Polling Duration ###
+When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state until the broker response includes `"state":"succeeded"` or `"state":"failed"`, or until a maximum polling duration is reached. If the max polling duration is reached, Cloud Foundry will cease polling and the operation state will be considered `failed`. The Cloud Foundry operator can configure this max polling duration in the BOSH deployment manifest using the property `properties.cc.broker_client_max_async_poll_duration_minutes` (defaults to 10080 minutes or 1 week).
+
+### Additional Resources ###
+
+* An example broker that implements this feature can be found at [Example Service Brokers](examples.html).
+* A demo video of the CLI user experience using the above broker can be found [here](https://youtu.be/Ij5KSKrAq9Q).
+
+## Provisioning ##
+
+When the broker receives a provision request from Cloud Controller, it should
+synchronously take whatever action is necessary to create a new service
+resource for the developer.
+The result of provisioning varies by service type, although there are a few
+common actions that work for many services.
+For a MySQL service, provisioning could result in:
+
+* An empty dedicated `mysqld` process running on its own VM.
+* An empty dedicated `mysqld` process running in a lightweight container on a
+shared VM.
+* An empty dedicated `mysqld` process running on a shared VM.
+* An empty dedicated database, on an existing shared running `mysqld`.
+* A database with business schema already there.
+* A copy of a full database, for example a QA database that is a copy of the
+production database.
+
+For non-data services, provisioning could just mean getting an account on an
+existing system.
+
+### Request ###
+
+##### Route #####
+`PUT /v2/service_instances/:instance_id`
+
+
Note: The :instance_id of a service instance is provided by the Cloud Controller. This ID will be used for future requests (bind and deprovision), so the broker must use it to correlate the resource it creates.

+
+##### Body #####
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Request fieldTypeDescription
organization_guid*stringThe Cloud Controller GUID of the organization under which the service is to be provisioned. Although most brokers will not use this field, it could be helpful in determining data placement or applying custom business rules.
plan_id*stringThe ID of the plan within the above service (from the catalog endpoint) that the user would like provisioned. Because plans have identifiers unique to a broker, this is enough information to determine what to provision.
service_id*stringThe ID of the service within the catalog above.
space_guid*stringSimilar to organization_guid, but for the space.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous provisioning. If this parameter is not included in the request, and the broker can only provision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.

+
+\* Fields with an asterisk are required.
+
+
+{
+  "organization_guid": "org-guid-here",
+  "plan_id":           "plan-guid-here",
+  "service_id":        "service-guid-here",
+  "space_guid":        "space-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  }
+}
+

+
+##### cURL #####
+
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
+  "organization_guid": "org-guid-here",
+  "plan_id":           "plan-guid-here",
+  "service_id":        "service-guid-here",
+  "space_guid":        "space-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  }
+}' -X PUT -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
+

+
+In this case, `instance_id` refers to the service instance id generated by Cloud
+Controller
+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+
Status CodeDescription
201 CreatedService instance has been created. The expected response body is below.
200 OK
+    May be returned if the service instance already exists and the requested parameters are identical to the existing service instance.
+    The expected response body is below.
+  
202 AcceptedService instance creation is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
409 ConflictShould be returned if the requested service instance already exists. The expected response body is {}.
422 Unprocessable EntityShould be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.

+
+Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
dashboard_urlstringThe URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL should contain enough information for the dashboard to identify the resource being accessed ("9189kdfsk0vfnku" in the example below). For information on how users can authenticate with service dashboards via SSO, see Dashboard Single Sign-On.
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..

+\* Fields with an asterisk are required.
+
+{
+ "dashboard_url": "http://example-dashboard.com/9189kdfsk0vfnku",
+ "operation": "task_10"
+}
+

+
+
+## Updating a Service Instance ##
+
+Brokers that implement this endpoint can enable users to modify attributes of an existing service instance. The first attribute Cloud Foundry supports users modifying is the service plan. This effectively enables users to upgrade or downgrade their service instance to other plans. To see how users make these requests, see [Managing Services](../devguide/services/managing-services.html#update_service).
+
+To enable this functionality, a broker declares support for each service by including `plan_updateable: true` in its [catalog endpoint](#catalog-mgmt). If this optional field is not included, Cloud Foundry will return a meaningful error to users for any plan change request, and will not make an API call to the broker. If this field is included and configured as true, Cloud Foundry will make API calls to the broker for all plan change requests, and it is up to the broker to validate whether a particular permutation of plan change is supported. Not all permutations of plan changes are expected to be supported. For example, a service may support upgrading from plan "shared small" to "shared large" but not to plan "dedicated". If a particular plan change is not supported, the broker should return a meaningful error message in response.
+
+### Request ###
+
+##### Route #####
+`PATCH /v2/service_instances/:instance_id`
+
+
Note: :instance_id is the global unique ID of a previously-provisioned service instance.

+
+##### Body #####
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Request FieldTypeDescription
service_id*stringThe ID of the service within the catalog above.
plan_idstringID of the new plan from the catalog.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
previous_valuesobjectInformation about the instance prior to the update.
previous_values.plan_idstringID of the plan prior to the update.
previous_values.service_idstringID of the service for the instance.
previous_values.organization_idstringID of the organization containing the instance.
previous_values.space_idstringID of the space containing the instance..
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous update. If this parameter is not included in the request, and the broker can only update an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.

+
+\* Fields with an asterisk are required.
+
+
+{
+  "service_id": "service-guid-here",
+  "plan_id": "plan-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  },
+  "previous_values": {
+    "plan_id": "old-plan-guid-here",
+    "service_id": "service-guid-here",
+    "organization_id": "org-guid-here",
+    "space_id": "space-guid-here"
+  }
+}
+

+
+##### cURL #####
+
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
+  "service_id": "service-guid-here",
+  "plan_id": "plan-guid-here",
+  "parameters":        {
+    "parameter1": 1,
+    "parameter2": "value"
+  },
+  "previous_values": {
+    "plan_id": "old-plan-guid-here",
+    "service_id": "service-guid-here",
+    "organization_id": "org-guid-here",
+    "space_id": "space-guid-here"
+  }
+}' -X PATCH -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
+

+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+
Status CodeDescription
200 OKNew plan is effective. The expected response body is {}.
202 AcceptedService instance update is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
422 Unprocessable entity
+    May be returned if the particular plan change requested is not supported or if the request cannot currently be fulfilled due to the state of the instance (eg. instance utilization is over the quota of the requested plan). Broker should include a user-facing message in the body; for details see Broker Errors.  Additionally, a 422 can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }.
+  

+
+Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..

+\* Fields with an asterisk are required.
+
+{
+ "operation": "task_10"
+}
+

+
+
+## Binding ##
+
+
Note: Not all services must be bindable --- some deliver value just from being provisioned. Brokers that offer services that are bindable should declare them as such using bindable: true in the Catalog. Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

+
+### Types of Binding ###
+
+#### Credentials ####
+
+Credentials are a set of information used by an application or a user to utilize the service instance. If `bindable:true` is declared for a service in the catalog endpoint, users may request generation of credentials either by binding the service instance to an application or by creating a service key. When a service instance is bound to an app, Cloud Foundry will send the app id with the request. When a service key is created, the app id is not included. If the broker supports generation of credentials it should return `credentials` in the response. Credentials should be unique whenever possible, so access can be revoked for one application or user without affecting another. For more information on credentials, see [Binding Credentials](binding-credentials.html).
+
+#### Application Log Streaming ####
+
+In response to a bind request for an application (`app_id` included), a broker may also enable streaming of application logs from Cloud Foundry to a consuming service instance by returning `syslog_drain_url`. For details, see [Application Log Streaming](app-log-streaming.html).
+
+#### Route Services ####
+
+If a broker has declared `"requires":["route_forwarding"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind a service to a route. When bound to a route, the route itself will be sent with the bind request. A route is an address used by clients to reach apps mapped to the route. In response a broker may return a `route_service_url` which Cloud Foundry will use to proxy any request for the route to the service instance at URL specified by `route_service_url`. A broker may declare `"requires":["route_forwarding"]` but not return `route_service_url`; this enables a broker to dynamically configure a network component already in the request path for the route, requiring no change in the Cloud Foundry router. For more information, see [Route Services](route-services.html).
+
+#### Volume Services (Experimental)####
+
+If a broker has declared `"requires":["volume_mount"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind one or more volumes to an application.  In response to a bind request a volume service broker should return a set of `volume_mount` instructions that Cloud Foundry will ensure are mounted into the application's containers.  For more information, see [Volume Services](volume-services.html)
+
+### Request ###
+
+##### Route #####
+`PUT /v2/service_instances/:instance_id/service_bindings/:binding_id`
+
+
Note: The :binding_id of a service binding is provided by the Cloud Controller.
+:instance_id is the ID of a previously-provisioned service instance; :binding_id
+will be used for future unbind requests, so the broker must use it to correlate
+the resource it creates.

+
+##### Body #####
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Request FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.
app_guidstringGUID of the application that you want to bind your service to. Will be included when users bind applications to service instances.
bind_resourceJSON objectA JSON object that contains the required fields of the resource being bound. Currently only app_guid for application bindings and route for route bindings are supported.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.

+
+\* Fields with an asterisk are required.
+
+
+{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "app_guid":     "app-guid-here",
+  "bind_resource":     {
+    "app_guid": "app-guid-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}
+

+
+
+{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "bind_resource":     {
+    "route": "route-url-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}
+

+
+##### cURL #####
+
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "app_guid":     "app-guid-here",
+  "bind_resource":     {
+    "app_guid": "app-guid-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}' -X PUT
+

+
+
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
+  "plan_id":      "plan-guid-here",
+  "service_id":   "service-guid-here",
+  "bind_resource":     {
+    "route": "route-url-here"
+  },
+  "parameters":        {
+    "parameter1-name-here": 1,
+    "parameter2-name-here": "parameter2-value-here"
+  }
+}' -X PUT
+

+
+In this case, `instance_id` refers to the id of an existing service instance in a previous provisioning, while `binding_id` is service binding id generated by Cloud Controller.
+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+
Status CodeDescription
201 CreatedBinding has been created. The expected response body is below.
200 OK
+    May be returned if the binding already exists and the requested parameters are identical to the existing binding.
+    The expected response body is below.
+  
409 ConflictShould be returned if the requested binding already exists. The expected response body is {}, though the description field can be used to return a user-facing error message, as described in Broker Errors.
422 Unprocessable EntityShould be returned if the broker requires that app_guid be included in the request body. The expected response body is: { "error": "RequiresApp", "description": "This service supports generation of credentials through binding an application only." }

+
+Responses with any other status code will be interpreted as a failure and an unbind request will be sent to the broker to prevent an orphan being created on the broker. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Response FieldTypeDescription
credentialsobjectA free-form hash of credentials that the bound application can use to access the service. For more information, see Binding Credentials.
syslog_drain_urlstringA URL to which Cloud Foundry should drain logs for the bound application. requires:syslog_drain must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Application Log Streaming.
route_service_urlstringA URL to which Cloud Foundry should proxy requests for the bound route. requires:route_forwarding must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Route Services.
volume_mountsarray-of-objectsAn array of volume mount instructions.  requires:volume_mount must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid.  For more information, see Volume Services

+
+
+	{
+	  "credentials": {
+	    "uri": "mysql://mysqluser:pass@mysqlhost:3306/dbname",
+	    "username": "mysqluser",
+	    "password": "pass",
+	    "host": "mysqlhost",
+	    "port": 3306,
+	    "database": "dbname"
+	  }
+	}
+

+
+## Unbinding ##
+
+
Note: Brokers that do not provide any bindable services do not need to implement the endpoint for unbind requests.

+
+When a broker receives an unbind request from Cloud Controller, it should
+delete any resources it created in bind.
+Usually this means that an application immediately cannot access the resource.
+
+### Request ###
+
+##### Route #####
+`DELETE /v2/service_instances/:instance_id/service_bindings/:binding_id`
+
+The `:binding_id` in the URL is the identifier of a previously created binding (the same `:binding_id` passed in the bind request). The request has no body, because DELETE requests generally do not have bodies.
+
+##### Parameters #####
+
+The request provides these query string parameters as useful hints for brokers.
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.

+
+\* Query parameters with an asterisk are required.
+
+##### cURL #####
+
+$ curl 'http://username:password@broker-url/v2/service_instances/:instance_id/
+  service_bindings/:binding_id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.9"
+

+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+  
+  
+
+
+
Status CodeDescription
200 OKBinding was deleted. The expected response body is {}.
410 GoneShould be returned if the binding does not exist. The expected response body is {}.

+
+Responses with any other status code will be interpreted as a failure and the binding will remain in the Cloud Controller database. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
+Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
Response fieldTypeDescription
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..

+\* Fields with an asterisk are required.
+
+{
+ "operation": "task_10"
+}
+

+
+## Deprovisioning ##
+
+When a broker receives a deprovision request from Cloud Controller, it should
+delete any resources it created during the provision.
+Usually this means that all resources are immediately reclaimed for future
+provisions.
+
+### Request ###
+
+##### Route #####
+`DELETE /v2/service_instances/:instance_id`
+
+The `:instance_id` in the URL is the identifier of a previously provisioned instance (the same
+`:instance_id` passed in the provision request).  The request has no body, because DELETE
+requests generally do not have bodies.
+
+##### Parameters #####
+
+The request provides these query string parameters as useful hints for brokers.
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the broker can only deprovision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.

+
+\* Query parameters with an asterisk are required.
+
+##### cURL #####
+
+$ curl 'http://username:password@broker-url/v2/service_instances/:instance_id?service_id=
+    service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.9"
+

+
+### Response ###
+
+
+
+
+  
+  
+
+
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+  
+  
+
+
+
Status CodeDescription
200 OKService instance was deleted. The expected response body is {}.
202 AcceptedService instance deletion is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
410 GoneShould be returned if the service instance does not exist. The expected response body is {}.
422 Unprocessable EntityShould be returned if the broker only supports asynchronous deprovisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.

+
+Responses with any other status code will be interpreted as a failure and the service instance will remain in the Cloud Controller database. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For a success response, the expected response body is `{}`.
+
+## Broker Errors ##
+
+### Response ###
+
+Broker failures beyond the scope of the well-defined HTTP response codes listed
+above (like 410 on delete) should return an appropriate HTTP response code
+(chosen to accurately reflect the nature of the failure) and a body containing a valid JSON Object (not an array).
+
+##### Body #####
+
+All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
+
+For error responses, the following fields are valid. Others will be ignored. If an empty JSON object is returned in the body `{}`, a generic message containing the HTTP response code returned by the broker will be displayed to the requestor.
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+
Response FieldTypeDescription
descriptionstringAn error message explaining why the request failed. This message will be displayed to the user who initiated the request.
+

+
+
+{
+  "description": "Something went wrong. Please contact support at http://support.example.com."
+}
+

+
+## Orphans ##
+
+The Cloud Controller is the source of truth for service instances and bindings. Service brokers are expected to have successfully provisioned all the instances and bindings Cloud Controller knows about, and none that it doesn't.
+
+Orphans can result if the broker does not return a response before a request from Cloud Controller times out (typically 60 seconds). For example, if a broker does not return a response to a provision request before Cloud Controller times out, the broker might eventually succeed in provisioning an instance after Cloud Controller considers the request a failure. This results in an orphan instance on the service side.
+
+To mitigate orphan instances and bindings, Cloud Controller will attempt to delete resources it cannot be sure were successfully created, and will keep trying to delete them until the broker responds with a success.
+
+More specifically, when a provision or bind request to the broker fails, Cloud Controller will immediately send a corresponding delete or unbind request. If the delete or unbind request fails, Cloud Controller will retry the delete or unbind request ten times with an exponental backoff schedule (over a period of 34 hours).
+
+
+
+
+  
+  
+  
+
+
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+  
+  
+  
+
+
+
Status codeResultOrphan mitigation
200Success
200 with malformed responseFailure
201Success
201 with malformed responseFailureYes
All other 2xxFailureYes
408Failure due to timeoutYes
All other 4xxBroker rejects request
5xxBroker errorYes
TimeoutFailureYes

+
+If the Cloud Controller encounters an internal error provisioning an instance or binding (for example, saving to the database fails), then the Cloud Controller will send a single delete or unbind request to the broker but will not retry.
+
+This orphan mitigation behavior was introduced in cf-release v196.
diff --git a/api.html.md.erb b/api.html.md.erb
deleted file mode 100644
index bdc4f23..0000000
--- a/api.html.md.erb
+++ /dev/null
@@ -1,1409 +0,0 @@
----
-title: Service Broker API v2.9
-owner: Services API
----
-
-<%= modified_date %>
-
-## Document Changelog ##
-
-[v2 API Change Log](v2-api-changelog.html)
-
-<%= partial "version_table.html" %>
-
-## Changes ##
-
-### Change Policy ###
-
-* Existing endpoints and fields will not be removed or renamed.
-* New optional endpoints, or new HTTP methods for existing endpoints, may be
-added to enable support for new features.
-* New fields may be added to existing request/response messages.
-These fields must be optional and should be ignored by clients and servers
-that do not understand them.
-
-### Changes Since v2.8 ###
-
-1. Querying `last_operation` now supports `service_id` and `plan_id` query parameters.
-1. Provision, Update, Deprovision responses now accepts an optional `operation` json param for async responses. This is used to by service brokers to return an state related to the operation. Provided back to the service broker via the `last_operation` call.
-1. Querying `last_operation` now supports `operation` param back to the service broker.
-
-## Dependencies ##
-
-v2.9 of the services API has been supported since:
-
-* [Final build 238](https://github.com/cloudfoundry/cf-release/tree/v238) of [cf-release](https://github.com/cloudfoundry/cf-release/)
-* v2.57.0 of the Cloud Controller API
-* CLI [v6.14.0](https://github.com/cloudfoundry/cli/releases/tag/v6.14.0)
-
-## API Overview ##
-
-The Cloud Foundry services API defines the contract between the Cloud
-Controller and the service broker.
-The broker is expected to implement several HTTP (or HTTPS) endpoints
-underneath a URI prefix.
-One or more services can be provided by a single broker, and load balancing
-enables horizontal scalability of redundant brokers.
-Multiple Cloud Foundry instances can be supported by a single broker using
-different URL prefixes and credentials.
-
-<%= image_tag("../images/v2services-new.png", :width =>"960", :height =>"720", :style => 'background-color:#fff') %>
-
-## API Version Header ##
-
-Requests from the Cloud Controller to the broker contain a header that defines
-the version number of the Broker API that Cloud Controller will use.
-This header will be useful in future minor revisions of the API to allow
-brokers to reject requests from Cloud Controllers that they do not understand.
-While minor API revisions will always be additive, it is possible that brokers
-will come to depend on a feature that was added after 2.0, so they may use this
-header to reject the request.
-Error messages from the broker in this situation should inform the operator of
-what the required and actual version numbers are so that an operator can go
-upgrade Cloud Controller and resolve the issue.
-A broker should respond with a `412 Precondition Failed` message when rejecting
-a request.
-
-The version numbers are in the format `MAJOR.MINOR`, using semantic versioning
-such that 2.9 comes before 2.10.
-An example of this header as of publication time is:
-
-`X-Broker-Api-Version: 2.9`
-
-## Authentication ##
-
-Cloud Controller (final release v145+) authenticates with the Broker using HTTP
-basic authentication (the `Authorization:` header) on every request and will
-reject any broker registrations that do not contain a username and password.
-The broker is responsible for checking the username and password and returning
-a `401 Unauthorized` message if credentials are invalid.
-Cloud Controller supports connecting to a broker using SSL if additional
-security is desired.
-
-## Catalog Management ##
-
-The first endpoint that a broker must implement is the service catalog.
-Cloud Controller will initially fetch this endpoint from all brokers and make
-adjustments to the user-facing service catalog stored in the Cloud Controller
-database.
-If the catalog fails to initially load or validate, Cloud Controller will not
-allow the operator to add the new broker and will give a meaningful error
-message.
-Cloud Controller will also update the catalog whenever a broker is updated, so
-you can use `update-service-broker` with no changes to force a catalog refresh.
-
-When Cloud Controller fetches a catalog from a broker, it will compare the
-broker's id for services and plans with the `unique_id` values for services and
-plans in the  Cloud Controller database.
-If a service or plan in the broker catalog has an id that is not present
-amongst the `unique_id` values in the database, a new record will be added to
-the database.
-If services or plans in the database are found with `unique_id`s that match the
-broker catalog's id, Cloud Controller will update the records to match
-the broker’s catalog.
-
-If the database has plans which are not found in the broker catalog, and there
-are no associated service instances, Cloud Controller will remove these plans
-from the database. Cloud Controller will then delete services that do not have associated plans
-from the database.
-If the database has plans which are not found in the broker catalog, and there
-**are** provisioned instances, the plan will be marked “inactive” and will
-no longer be visible in the marketplace catalog or be provisionable.
-
-
-### Request ###
-
-#### Route ####
-`GET /v2/catalog`
-
-#### cURL ####
-
- $ curl -H "X-Broker-API-Version: 2.9" http://username:password@broker-url/v2/catalog
-

-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-
Status CodeDescription
200 OKThe expected response body is below.

-
-#### Body - Schema of Service Objects ####
-
-CLI and web clients have different needs with regard to service and plan names.
-A CLI-friendly string is all lowercase, with no spaces.
-Keep it short -- imagine a user having to type it as an argument for a longer
-command.
-A web-friendly display name is camel-cased with spaces and punctuation supported.
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
services*array-of-service-objectsSchema of service objects defined below.

-
-
 Service Objects 

-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-  
-  
-  
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
   name*stringThe CLI-friendly name of the service that will appear in the catalog. All lowercase, no spaces.
   id*stringAn identifier used to correlate this service in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended. 
   description*stringA short description of the service that will appear in the catalog.
   tagsarray-of-stringsTags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp.
   requiresarray-of-stringsA 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; for more info see Application Log Streaming, Route Services and Volume Services.
   max_db_per_node:strings
   bindable*booleanWhether the service can be bound to applications.
   metadataobjectA list of metadata for a service offering. For more information, see Service Metadata.
   dashboard_clientobjectContains the data necessary to activate the Dashboard SSO feature for this service
   plan_updateableboolean
-    Whether the service supports upgrade/downgrade for some plans.
-    

-    Please note that the misspelling of the attribute plan_updatable to plan_updateable was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility.
-  
   plans*array-of-objectsA list of plans for this service, schema is defined below.

-
-
 Dashboard Client Object  

-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
   idstringThe id of the Oauth2 client that the service intends to use. The name may be taken, in which case the updat will return an error to the operator
   secretstringA secret for the dashboard client
   redirect_uristringA domain for the service dashboard that will be whitelisted by the UAA to enable SSO

-
-
-
 Plan Object  

-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
   id*stringAn identifier used to correlate this plan in future requests to the catalog. This must be unique within Cloud Foundry, using a GUID is recommended.
   name*stringThe CLI-friendly name of the plan that will appear in the catalog. All lowercase, no spaces.
   description*stringA short description of the service that will appear in the catalog.
   metadataobjectA list of metadata for a service plan. For more information, see Service Metadata.
   freebooleanThis field allows the plan to be limited by the non_basic_services_allowed field in a Cloud Foundry Quota, see Quota Plans. Default: true

-
-\* Fields with an asterisk are required.
-
-
-{
-  "services": [{
-    "name": "fake-service",
-    "id": "acb56d7c-XXXX-XXXX-XXXX-feb140a59a66",
-    "description": "fake service",
-    "tags": ["no-sql", "relational"],
-    "requires": ["route_forwarding"],
-    "max_db_per_node": 5,
-    "bindable": true,
-    "metadata": {
-      "provider": {
-        "name": "The name"
-      },
-      "listing": {
-        "imageUrl": "http://catgifpage.com/cat.gif",
-        "blurb": "Add a blurb here",
-        "longDescription": "A long time ago, in a galaxy far far away..."
-      },
-      "displayName": "The Fake Broker"
-    },
-    "dashboard_client": {
-      "id": "398e2f8e-XXXX-XXXX-XXXX-19a71ecbcf64",
-      "secret": "277cabb0-XXXX-XXXX-XXXX-7822c0a90e5d",
-      "redirect_uri": "http://localhost:1234"
-    },
-    "plan_updateable": true,
-    "plans": [{
-      "name": "fake-plan",
-      "id": "d3031751-XXXX-XXXX-XXXX-a42377d3320e",
-      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections",
-      "max_storage_tb": 5,
-      "metadata": {
-        "cost": 0,
-        "bullets": [{
-          "content": "Shared fake server"
-        }, {
-          "content": "5 TB storage"
-        }, {
-          "content": "40 concurrent connections"
-        }]
-      }
-    }, {
-      "name": "fake-async-plan",
-      "id": "0f4008b5-XXXX-XXXX-XXXX-dace631cd648",
-      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections. 100 async",
-      "max_storage_tb": 5,
-      "metadata": {
-        "cost": 0,
-        "bullets": [{
-          "content": "40 concurrent connections"
-        }]
-      }
-    }, {
-      "name": "fake-async-only-plan",
-      "id": "8d415f6a-XXXX-XXXX-XXXX-e61f3baa1c77",
-      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections. 100 async",
-      "max_storage_tb": 5,
-      "metadata": {
-        "cost": 0,
-        "bullets": [{
-          "content": "40 concurrent connections"
-        }]
-      }
-    }]
-  }]
-}
-

-
-
-### Adding a Broker to Cloud Foundry ###
-
-Once you've implemented the first endpoint `GET /v2/catalog` above, you'll want
-to [register the broker with CF](managing-service-brokers.html#register-broker)
-to make your services and plans available to end users.
-
-## Asynchronous Operations ##
-
-Previously, Cloud Foundry only supported synchronous integration with service brokers. Brokers must return a valid response within 60 seconds and if the response is `201 CREATED`, users expect a service instance to be usable. This limits the services brokers can offer to those that can be provisioned in 60 seconds; brokers could return a success prematurely, but this leaves users wondering why their service instance is not usable and when it will be.
-
-With support for Asynchronous Operations, brokers still must respond within 60 seconds but may now return a `202 ACCEPTED`, indicating that the requested operation has been accepted but is not complete. This triggers Cloud Foundry to poll a new endpoint `/v2/service_instances/:guid/last_operation` until the broker indicates that the requested operation has succeeded or failed. During the intervening time, end users are able to discover the state of the requested operation using Cloud Foundry API clients such as the CLI.
-
-For an operation to be executed asynchronously, all three components (CF API client, CF, and broker) must support the feature. The parameter `accepts_incomplete=true` must be passed in a request by the CF API client, triggering CF to include the same parameter in a request to the broker. The broker can then choose to execute the request synchronously or asynchronously.
-
-If the broker executes the request asynchronously, the response must use the status code `202 ACCEPTED`; the response body should be the same as if the broker were serving the request synchronously.
-
-
Note: Asynchronous Operations are currently supported only for provision, update, and deprovision. Bind and unbind will be added once the feature is considered stable.

-
-If the `accepts_incomplete=true` parameter is not included, and the broker cannot fulfill the request synchronously (guaranteeing that the operation is complete on response), then the broker should reject the request with the status code `422 UNPROCESSABLE ENTITY` and the following body:
-
-
-{
-  "error": "AsyncRequired",
-  "description": "This service plan requires client support for asynchronous service operations."
-}
-

-
-To execute a request synchronously, the broker need only return the usual status codes; `201 CREATED` for create, and `200 OK` for update and delete.
-
-### Sequence Diagram ###
-
-  <%= image_tag("images/async-service-broker-flow.png", :width =>"1250", :height =>"823", :style => 'background-color:#fff') %>
-
-
-### Blocking Operations ###
-
-The Cloud Controller ensures that service brokers do not receive requests for an instance while an asynchronous operation is in progress. For example, if a broker is in the process of provisioning an instance asynchronously, the Cloud Controller will not allow any update, bind, unbind, or deprovision requests to be made through the platform. A user who attempts to perform one of these actions while an operation is already in progress will get an HTTP 400 with error message "Another operation for this service instance is in progress."
-
-### When to use Asynchronous Service Operations ###
-
-Service brokers should respond to all Cloud Controller requests within 60 seconds. Brokers that can guarantee completion of the requested operation with the response may return the synchronous response (e.g. `201 CREATED` for a provision request). Brokers that cannot guarantee completion of the operation with the response should implement support for asynchronous provisioning. Support for synchronous or asynchronous responses may vary by service offering, even by service plan.
-
-## Polling Last Operation (async only) ##
-
-When a broker returns status code `202 ACCEPTED` for [provision](#provisioning), [update](#updating_service_instance), or [deprovision](#deprovisioning), Cloud Foundry will begin to poll the `/v2/service_instances/:guid/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`.
-
-Valid values for `state` are `in progress`, `succeeded`, and `failed`. Cloud Foundry will poll the `last_operation` endpoint as long as the broker returns `"state": "in progress"`. Returning `"state": "succeeded"` or `"state": "failed"` will cause Cloud Foundry to cease polling. The value provided for `description` will be passed through to the CF API client and can be used to provide additional detail for users about the state of the operation.
-
-### Request ###
-
-##### Route #####
-`GET /v2/service_instances/:instance_id/last_operation`
-
-##### Parameters #####
-
-The request provides these query string parameters as useful hints for brokers.
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.
operationstringThe field optionally returned by the service broker on Provision, Update, Deprovision async responses. Repesents any state the service broker responsed with as a URL encoded string..

-
-\* Query parameters with an asterisk are required.
-
-##### cURL #####
-
-$ curl http://username:password@broker-url/v2/service_instances/:instance_id/last_operation
-

-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-  
-  
-
-
-
Status CodeDescription
200 OKThe expected response body is below.
410 GONEAppropriate only for asynchronous delete requests. Cloud Foundry will consider this response a success and remove the resource from its database. The expected response body is {}. Returning this while Cloud Foundry is polling for create or update operations will be interpreted as an invalid response and Cloud Foundry will continue polling.

-
-Responses with any other status code will be interpreted as an error or invalid response; Cloud Foundry will continue polling until the broker returns a valid response or the [maximum polling duration](#max-polling-duration) is reached. Brokers may use the `description` field to expose user-facing error messages about the operation state; for more info see [Broker Errors](api.html#broker-errors).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For success responses, the following fields are valid.
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
state*stringValid values are in progress, succeeded, and failed. While "state": "in progress", Cloud Foundry will continue polling. A response with "state": "succeeded" or "state": "failed" will cause Cloud Foundry to cease polling.
descriptionstringOptional field. A user-facing message displayed to the Cloud Foundry API client. Can be used to tell the user details about the status of the operation.

-
-\* Fields with an asterisk are required.
-
-
-{
-  "state": "in progress",
-  "description": "Creating service (10% complete)."
-}
-

-
-###  Polling Interval ###
-When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state at a configured interval. The Cloud Foundry operator can configure this interval in the BOSH deployment manifest using the property `properties.cc.broker_client_default_async_poll_interval_seconds` (defaults to 60 seconds). The maximum supported polling interval is 86400 seconds (24 hours).
-
-### Maximum Polling Duration ###
-When a broker responds asynchronously to a request from Cloud Foundry containing the `accepts_incomplete=true` parameter, Cloud Foundry will poll the broker for the operation state until the broker response includes `"state":"succeeded"` or `"state":"failed"`, or until a maximum polling duration is reached. If the max polling duration is reached, Cloud Foundry will cease polling and the operation state will be considered `failed`. The Cloud Foundry operator can configure this max polling duration in the BOSH deployment manifest using the property `properties.cc.broker_client_max_async_poll_duration_minutes` (defaults to 10080 minutes or 1 week).
-
-### Additional Resources ###
-
-* An example broker that implements this feature can be found at [Example Service Brokers](examples.html).
-* A demo video of the CLI user experience using the above broker can be found [here](https://youtu.be/Ij5KSKrAq9Q).
-
-## Provisioning ##
-
-When the broker receives a provision request from Cloud Controller, it should
-synchronously take whatever action is necessary to create a new service
-resource for the developer.
-The result of provisioning varies by service type, although there are a few
-common actions that work for many services.
-For a MySQL service, provisioning could result in:
-
-* An empty dedicated `mysqld` process running on its own VM.
-* An empty dedicated `mysqld` process running in a lightweight container on a
-shared VM.
-* An empty dedicated `mysqld` process running on a shared VM.
-* An empty dedicated database, on an existing shared running `mysqld`.
-* A database with business schema already there.
-* A copy of a full database, for example a QA database that is a copy of the
-production database.
-
-For non-data services, provisioning could just mean getting an account on an
-existing system.
-
-### Request ###
-
-##### Route #####
-`PUT /v2/service_instances/:instance_id`
-
-
Note: The :instance_id of a service instance is provided by the Cloud Controller. This ID will be used for future requests (bind and deprovision), so the broker must use it to correlate the resource it creates.

-
-##### Body #####
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Request fieldTypeDescription
organization_guid*stringThe Cloud Controller GUID of the organization under which the service is to be provisioned. Although most brokers will not use this field, it could be helpful in determining data placement or applying custom business rules.
plan_id*stringThe ID of the plan within the above service (from the catalog endpoint) that the user would like provisioned. Because plans have identifiers unique to a broker, this is enough information to determine what to provision.
service_id*stringThe ID of the service within the catalog above.
space_guid*stringSimilar to organization_guid, but for the space.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous provisioning. If this parameter is not included in the request, and the broker can only provision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.

-
-\* Fields with an asterisk are required.
-
-
-{
-  "organization_guid": "org-guid-here",
-  "plan_id":           "plan-guid-here",
-  "service_id":        "service-guid-here",
-  "space_guid":        "space-guid-here",
-  "parameters":        {
-    "parameter1": 1,
-    "parameter2": "value"
-  }
-}
-

-
-##### cURL #####
-
-$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
-  "organization_guid": "org-guid-here",
-  "plan_id":           "plan-guid-here",
-  "service_id":        "service-guid-here",
-  "space_guid":        "space-guid-here",
-  "parameters":        {
-    "parameter1": 1,
-    "parameter2": "value"
-  }
-}' -X PUT -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
-

-
-In this case, `instance_id` refers to the service instance id generated by Cloud
-Controller
-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-
Status CodeDescription
201 CreatedService instance has been created. The expected response body is below.
200 OK
-    May be returned if the service instance already exists and the requested parameters are identical to the existing service instance.
-    The expected response body is below.
-  
202 AcceptedService instance creation is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
409 ConflictShould be returned if the requested service instance already exists. The expected response body is {}.
422 Unprocessable EntityShould be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.

-
-Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
dashboard_urlstringThe URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL should contain enough information for the dashboard to identify the resource being accessed ("9189kdfsk0vfnku" in the example below). For information on how users can authenticate with service dashboards via SSO, see Dashboard Single Sign-On.
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..

-\* Fields with an asterisk are required.
-
-{
- "dashboard_url": "http://example-dashboard.com/9189kdfsk0vfnku",
- "operation": "task_10"
-}
-

-
-
-## Updating a Service Instance ##
-
-Brokers that implement this endpoint can enable users to modify attributes of an existing service instance. The first attribute Cloud Foundry supports users modifying is the service plan. This effectively enables users to upgrade or downgrade their service instance to other plans. To see how users make these requests, see [Managing Services](../devguide/services/managing-services.html#update_service).
-
-To enable this functionality, a broker declares support for each service by including `plan_updateable: true` in its [catalog endpoint](#catalog-mgmt). If this optional field is not included, Cloud Foundry will return a meaningful error to users for any plan change request, and will not make an API call to the broker. If this field is included and configured as true, Cloud Foundry will make API calls to the broker for all plan change requests, and it is up to the broker to validate whether a particular permutation of plan change is supported. Not all permutations of plan changes are expected to be supported. For example, a service may support upgrading from plan "shared small" to "shared large" but not to plan "dedicated". If a particular plan change is not supported, the broker should return a meaningful error message in response.
-
-### Request ###
-
-##### Route #####
-`PATCH /v2/service_instances/:instance_id`
-
-
Note: :instance_id is the global unique ID of a previously-provisioned service instance.

-
-##### Body #####
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Request FieldTypeDescription
service_id*stringThe ID of the service within the catalog above.
plan_idstringID of the new plan from the catalog.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.
previous_valuesobjectInformation about the instance prior to the update.
previous_values.plan_idstringID of the plan prior to the update.
previous_values.service_idstringID of the service for the instance.
previous_values.organization_idstringID of the organization containing the instance.
previous_values.space_idstringID of the space containing the instance..
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous update. If this parameter is not included in the request, and the broker can only update an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.

-
-\* Fields with an asterisk are required.
-
-
-{
-  "service_id": "service-guid-here",
-  "plan_id": "plan-guid-here",
-  "parameters":        {
-    "parameter1": 1,
-    "parameter2": "value"
-  },
-  "previous_values": {
-    "plan_id": "old-plan-guid-here",
-    "service_id": "service-guid-here",
-    "organization_id": "org-guid-here",
-    "space_id": "space-guid-here"
-  }
-}
-

-
-##### cURL #####
-
-$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
-  "service_id": "service-guid-here",
-  "plan_id": "plan-guid-here",
-  "parameters":        {
-    "parameter1": 1,
-    "parameter2": "value"
-  },
-  "previous_values": {
-    "plan_id": "old-plan-guid-here",
-    "service_id": "service-guid-here",
-    "organization_id": "org-guid-here",
-    "space_id": "space-guid-here"
-  }
-}' -X PATCH -H "X-Broker-API-Version: 2.9" -H "Content-Type: application/json"
-

-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-
Status CodeDescription
200 OKNew plan is effective. The expected response body is {}.
202 AcceptedService instance update is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
422 Unprocessable entity
-    May be returned if the particular plan change requested is not supported or if the request cannot currently be fulfilled due to the state of the instance (eg. instance utilization is over the quota of the requested plan). Broker should include a user-facing message in the body; for details see Broker Errors.  Additionally, a 422 can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }.
-  

-
-Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..

-\* Fields with an asterisk are required.
-
-{
- "operation": "task_10"
-}
-

-
-
-## Binding ##
-
-
Note: Not all services must be bindable --- some deliver value just from being provisioned. Brokers that offer services that are bindable should declare them as such using bindable: true in the Catalog. Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.

-
-### Types of Binding ###
-
-#### Credentials ####
-
-Credentials are a set of information used by an application or a user to utilize the service instance. If `bindable:true` is declared for a service in the catalog endpoint, users may request generation of credentials either by binding the service instance to an application or by creating a service key. When a service instance is bound to an app, Cloud Foundry will send the app id with the request. When a service key is created, the app id is not included. If the broker supports generation of credentials it should return `credentials` in the response. Credentials should be unique whenever possible, so access can be revoked for one application or user without affecting another. For more information on credentials, see [Binding Credentials](binding-credentials.html).
-
-#### Application Log Streaming ####
-
-In response to a bind request for an application (`app_id` included), a broker may also enable streaming of application logs from Cloud Foundry to a consuming service instance by returning `syslog_drain_url`. For details, see [Application Log Streaming](app-log-streaming.html).
-
-#### Route Services ####
-
-If a broker has declared `"requires":["route_forwarding"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind a service to a route. When bound to a route, the route itself will be sent with the bind request. A route is an address used by clients to reach apps mapped to the route. In response a broker may return a `route_service_url` which Cloud Foundry will use to proxy any request for the route to the service instance at URL specified by `route_service_url`. A broker may declare `"requires":["route_forwarding"]` but not return `route_service_url`; this enables a broker to dynamically configure a network component already in the request path for the route, requiring no change in the Cloud Foundry router. For more information, see [Route Services](route-services.html).
-
-#### Volume Services (Experimental)####
-
-If a broker has declared `"requires":["volume_mount"]` for a service in the Catalog endpoint, Cloud Foundry will permit a user to bind one or more volumes to an application.  In response to a bind request a volume service broker should return a set of `volume_mount` instructions that Cloud Foundry will ensure are mounted into the application's containers.  For more information, see [Volume Services](volume-services.html)
-
-### Request ###
-
-##### Route #####
-`PUT /v2/service_instances/:instance_id/service_bindings/:binding_id`
-
-
Note: The :binding_id of a service binding is provided by the Cloud Controller.
-:instance_id is the ID of a previously-provisioned service instance; :binding_id
-will be used for future unbind requests, so the broker must use it to correlate
-the resource it creates.

-
-##### Body #####
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Request FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.
app_guidstringGUID of the application that you want to bind your service to. Will be included when users bind applications to service instances.
bind_resourceJSON objectA JSON object that contains the required fields of the resource being bound. Currently only app_guid for application bindings and route for route bindings are supported.
parametersJSON objectCloud Foundry API clients can provide a JSON object of configuration parameters with their request and this value will be passed through to the service broker. Brokers are responsible for validation.

-
-\* Fields with an asterisk are required.
-
-
-{
-  "plan_id":      "plan-guid-here",
-  "service_id":   "service-guid-here",
-  "app_guid":     "app-guid-here",
-  "bind_resource":     {
-    "app_guid": "app-guid-here"
-  },
-  "parameters":        {
-    "parameter1-name-here": 1,
-    "parameter2-name-here": "parameter2-value-here"
-  }
-}
-

-
-
-{
-  "plan_id":      "plan-guid-here",
-  "service_id":   "service-guid-here",
-  "bind_resource":     {
-    "route": "route-url-here"
-  },
-  "parameters":        {
-    "parameter1-name-here": 1,
-    "parameter2-name-here": "parameter2-value-here"
-  }
-}
-

-
-##### cURL #####
-
-$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
-  "plan_id":      "plan-guid-here",
-  "service_id":   "service-guid-here",
-  "app_guid":     "app-guid-here",
-  "bind_resource":     {
-    "app_guid": "app-guid-here"
-  },
-  "parameters":        {
-    "parameter1-name-here": 1,
-    "parameter2-name-here": "parameter2-value-here"
-  }
-}' -X PUT
-

-
-
-$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id -d '{
-  "plan_id":      "plan-guid-here",
-  "service_id":   "service-guid-here",
-  "bind_resource":     {
-    "route": "route-url-here"
-  },
-  "parameters":        {
-    "parameter1-name-here": 1,
-    "parameter2-name-here": "parameter2-value-here"
-  }
-}' -X PUT
-

-
-In this case, `instance_id` refers to the id of an existing service instance in a previous provisioning, while `binding_id` is service binding id generated by Cloud Controller.
-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-
Status CodeDescription
201 CreatedBinding has been created. The expected response body is below.
200 OK
-    May be returned if the binding already exists and the requested parameters are identical to the existing binding.
-    The expected response body is below.
-  
409 ConflictShould be returned if the requested binding already exists. The expected response body is {}, though the description field can be used to return a user-facing error message, as described in Broker Errors.
422 Unprocessable EntityShould be returned if the broker requires that app_guid be included in the request body. The expected response body is: { "error": "RequiresApp", "description": "This service supports generation of credentials through binding an application only." }

-
-Responses with any other status code will be interpreted as a failure and an unbind request will be sent to the broker to prevent an orphan being created on the broker. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Response FieldTypeDescription
credentialsobjectA free-form hash of credentials that the bound application can use to access the service. For more information, see Binding Credentials.
syslog_drain_urlstringA URL to which Cloud Foundry should drain logs for the bound application. requires:syslog_drain must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Application Log Streaming.
route_service_urlstringA URL to which Cloud Foundry should proxy requests for the bound route. requires:route_forwarding must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid. For details, see Route Services.
volume_mountsarray-of-objectsAn array of volume mount instructions.  requires:volume_mount must be declared in the catalog endpoint or Cloud Foundry will consider the response invalid.  For more information, see Volume Services

-
-
-	{
-	  "credentials": {
-	    "uri": "mysql://mysqluser:pass@mysqlhost:3306/dbname",
-	    "username": "mysqluser",
-	    "password": "pass",
-	    "host": "mysqlhost",
-	    "port": 3306,
-	    "database": "dbname"
-	  }
-	}
-

-
-## Unbinding ##
-
-
Note: Brokers that do not provide any bindable services do not need to implement the endpoint for unbind requests.

-
-When a broker receives an unbind request from Cloud Controller, it should
-delete any resources it created in bind.
-Usually this means that an application immediately cannot access the resource.
-
-### Request ###
-
-##### Route #####
-`DELETE /v2/service_instances/:instance_id/service_bindings/:binding_id`
-
-The `:binding_id` in the URL is the identifier of a previously created binding (the same `:binding_id` passed in the bind request). The request has no body, because DELETE requests generally do not have bodies.
-
-##### Parameters #####
-
-The request provides these query string parameters as useful hints for brokers.
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.

-
-\* Query parameters with an asterisk are required.
-
-##### cURL #####
-
-$ curl 'http://username:password@broker-url/v2/service_instances/:instance_id/
-  service_bindings/:binding_id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.9"
-

-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-  
-  
-
-
-
Status CodeDescription
200 OKBinding was deleted. The expected response body is {}.
410 GoneShould be returned if the binding does not exist. The expected response body is {}.

-
-Responses with any other status code will be interpreted as a failure and the binding will remain in the Cloud Controller database. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
-
-##### Body #####
-
-Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For success responses, the following fields are supported. Others will be ignored. For error responses, see [Broker Errors](#broker-errors).
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-
Response fieldTypeDescription
operationstringFor async responses, service brokers can return operation state as a string. This field will be provided back to the service broker on `last_operation` requests as a URL encoded query param..

-\* Fields with an asterisk are required.
-
-{
- "operation": "task_10"
-}
-

-
-## Deprovisioning ##
-
-When a broker receives a deprovision request from Cloud Controller, it should
-delete any resources it created during the provision.
-Usually this means that all resources are immediately reclaimed for future
-provisions.
-
-### Request ###
-
-##### Route #####
-`DELETE /v2/service_instances/:instance_id`
-
-The `:instance_id` in the URL is the identifier of a previously provisioned instance (the same
-`:instance_id` passed in the provision request).  The request has no body, because DELETE
-requests generally do not have bodies.
-
-##### Parameters #####
-
-The request provides these query string parameters as useful hints for brokers.
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Query-String FieldTypeDescription
service_id*stringID of the service from the catalog.
plan_id*stringID of the plan from the catalog.
accepts_incompletebooleanA value of true indicates that both the Cloud Controller and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the broker can only deprovision an instance of the requested plan asynchronously, the broker should reject the request with a 422 as described below.

-
-\* Query parameters with an asterisk are required.
-
-##### cURL #####
-
-$ curl 'http://username:password@broker-url/v2/service_instances/:instance_id?service_id=
-    service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.9"
-

-
-### Response ###
-
-
-
-
-  
-  
-
-
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-  
-  
-
-
-
Status CodeDescription
200 OKService instance was deleted. The expected response body is {}.
202 AcceptedService instance deletion is in progress. This triggers Cloud Controller to poll the Service Instance Last Operation Endpoint for operation status.
410 GoneShould be returned if the service instance does not exist. The expected response body is {}.
422 Unprocessable EntityShould be returned if the broker only supports asynchronous deprovisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.

-
-Responses with any other status code will be interpreted as a failure and the service instance will remain in the Cloud Controller database. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For a success response, the expected response body is `{}`.
-
-## Broker Errors ##
-
-### Response ###
-
-Broker failures beyond the scope of the well-defined HTTP response codes listed
-above (like 410 on delete) should return an appropriate HTTP response code
-(chosen to accurately reflect the nature of the failure) and a body containing a valid JSON Object (not an array).
-
-##### Body #####
-
-All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned.
-
-For error responses, the following fields are valid. Others will be ignored. If an empty JSON object is returned in the body `{}`, a generic message containing the HTTP response code returned by the broker will be displayed to the requestor.
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-
Response FieldTypeDescription
descriptionstringAn error message explaining why the request failed. This message will be displayed to the user who initiated the request.
-

-
-
-{
-  "description": "Something went wrong. Please contact support at http://support.example.com."
-}
-

-
-## Orphans ##
-
-The Cloud Controller is the source of truth for service instances and bindings. Service brokers are expected to have successfully provisioned all the instances and bindings Cloud Controller knows about, and none that it doesn't.
-
-Orphans can result if the broker does not return a response before a request from Cloud Controller times out (typically 60 seconds). For example, if a broker does not return a response to a provision request before Cloud Controller times out, the broker might eventually succeed in provisioning an instance after Cloud Controller considers the request a failure. This results in an orphan instance on the service side.
-
-To mitigate orphan instances and bindings, Cloud Controller will attempt to delete resources it cannot be sure were successfully created, and will keep trying to delete them until the broker responds with a success.
-
-More specifically, when a provision or bind request to the broker fails, Cloud Controller will immediately send a corresponding delete or unbind request. If the delete or unbind request fails, Cloud Controller will retry the delete or unbind request ten times with an exponental backoff schedule (over a period of 34 hours).
-
-
-
-
-  
-  
-  
-
-
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-  
-  
-  
-
-
-
Status codeResultOrphan mitigation
200Success
200 with malformed responseFailure
201Success
201 with malformed responseFailureYes
All other 2xxFailureYes
408Failure due to timeoutYes
All other 4xxBroker rejects request
5xxBroker errorYes
TimeoutFailureYes

-
-If the Cloud Controller encounters an internal error provisioning an instance or binding (for example, saving to the database fails), then the Cloud Controller will send a single delete or unbind request to the broker but will not retry.
-
-This orphan mitigation behavior was introduced in cf-release v196.
diff --git a/api.html.md.erb b/api.html.md.erb
new file mode 120000
index 0000000..0494dd3
--- /dev/null
+++ b/api.html.md.erb
@@ -0,0 +1 @@
+api-v2.9.html.md.erb
\ No newline at end of file