Service Broker API v2.8

Page last updated: December 4, 2015

Document Changelog

v2 API Change Log

Versions

Two major versions of the Service Broker API are currently supported by Cloud Foundry, v1 and v2. As v1 is deprecated and support will be removed at the end of 2015, it is recommended that all new brokers implement v2 and that current brokers are upgraded.

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.
2. 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.
3. 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 of cf-release
• v2.44.0 of the Cloud Controller API
• CLI 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.

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 plan 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_ids that match the broker catalog’s id, Cloud Controller will update 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

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.

* 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 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 can not 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

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 can not guarantee completion of the operation with the response should implement support for asynchronous provisioning. Support for asynchronous 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, update, or deprovision, 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

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 is reached. Brokers may use the description field to expose user-facing error messages about the operation state; for more info see 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.

{
  "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.
• A demo video of the CLI user experience using the above broker can be found here.

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

{
  "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

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.

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.

{
 "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.

To enable this functionality, a broker declares support for each service by including plan_updateable: true in its catalog endpoint. 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

{
  "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

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.

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.

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.

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.

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

{
  "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

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.

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.

    {
      "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.

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

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.

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.

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

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.

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.

{
  "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).

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.