Service Broker API

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 in the next major version of Cloud Foundry, it is recommended that all new brokers implement v2 and that current brokers are upgraded.

Current Version Past Versions
2.3 2.2
2.1
2.0
v1 (unversioned)

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.2

The key change from v2.2 to v2.3 of the Services API is the addition of SSO functionality for users to access external service dashboard pages.

  • A service can request a dashboard client in the service broker catalog.

For details, see the Dashboard SSO docs

Dependencies

v2.3 of the services API has been supported since final build 169 of cf-release.

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.3

Authentication

Cloud Controller (final release v145+) authenticates with the Broker using HTTP basic authentication (the Authentication: 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 http://username:password@broker-url/v2/catalog

Response

Status Code Description
200 OK The 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 field Type Description
services* array-of-objects Schema of service objects defined below:
   id* string An 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* string The CLI-friendly name of the service that will appear in the catalog. All lowercase, no spaces.
   description* string A short description of the service that will appear in the catalog.
   bindable* boolean Whether the service can be bound to applications.
   tags array-of-strings Tags 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. Eg. mysql, relational, redis, key-value, caching, messaging, amqp.
   metadata object A list of metadata for a service offering. For more information, see Service Metadata.
   requires array-of-strings A list of permissions that the user would have to give the service, if they provision it. The only permission currently supported is syslog_drain.
   plans* array-of-objects A list of plans for this service, schema defined below:
      id* string An 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* string The CLI-friendly name of the plan that will appear in the catalog. All lowercase, no spaces.
      description* string A short description of the service that will appear in the catalog.
      metadata object A list of metadata for a service plan. For more information, see Service Metadata.
      free boolean This 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_client object Contains the data necessary to activate the Dashboard SSO feature for this service
      id string The 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
      secret string A secret for the dashboard client
      redirect_uri string A 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 to make your services and plans available to end users.

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/:id

Note: the :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 field Type Description
service_id* string The ID of the service within the catalog above. While not strictly necessary, some brokers might make use of this ID.
plan_id* string The 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.
organization_guid* string The 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.
space_guid* string Similar to organization_guid, but for the space.
{
  "service_id":        "service-guid-here",
  "plan_id":           "plan-guid-here",
  "organization_guid": "org-guid-here",
  "space_guid":        "space-guid-here"
}
cURL
$ curl http://username:password@broker-url/v2/service_instances/:id -d '{
  "service_id":        "service-guid-here",
  "plan_id":           "plan-guid-here",
  "organization_guid": "org-guid-here",
  "space_guid":        "space-guid-here"
}' -X PUT

In this case, id refers to the service instance id generated by Cloud Controller

Response

Status Code Description
201 Created Service instance has been created. The expected response body is below.
409 Conflict Shall be returned if the requested service instance already exists. The expected response body is “{}”
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.

All other status codes will be interpreted as an error and cloud controller will inform the user that the provision failed.

We have chosen to require empty JSON in the response 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.

Body
Response field Type Description
dashboard_url 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.
{
 "dashboard_url": "http://mongomgmthost/databases/9189kdfsk0vfnku"
}

Binding

Note: Not all services must be bindable — some derive their value just from being provisioned. Brokers that do not provide any bindable services do not need to implement the endpoint for bind requests

When the broker receives a bind request from the Cloud Controller, it should return information which helps an application to utilize the provisioned resource. This information is generically referred to as credentials. Applications should be issued unique credentials whenever possible, so one application’s access can be revoked without affecting other bound applications. For more information on credentials, see Binding Credentials.

Request

Route

PUT /v2/service_instances/:instance_id/service_bindings/:id

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

Body
Request Field Type Description
service_id* string ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id* string ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.
app_guid* string GUID of the application that you want to bind your service to.
{
  "plan_id": "plan-guid-here",
  "service_id": "service-guid-here",
  "app_guid": "app-guid-here"
}
cURL
$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:id -d '{
  "plan_id": "plan-guid-here",
  "service_id": "service-guid-here",
  "app_guid": "app-guid-here"
}' -X PUT

In this case, instance_id refers to the id of an existing service instance in a previous provisioning, while id is service binding id generated by Cloud Controller.

Response

Status Code Description
201 Created Binding has been created. The expected response body is below.
409 Conflict Shall be returned if the requested binding already exists. The expected response body is “{}”
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.

All other status codes will be interpreted as an error and cloud controller will inform the user that the bind failed. Additionally, an unbind request will be sent to the broker to prevent an orphan being created on the broker.

We have chosen to require empty JSON in the response 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.

Body
Response Field Type Description
credentials object A free-form hash of credentials that the bound application can use to access the service. For more information, see Binding Credentials.
syslog_drain_url string A URL to which Cloud Foundry should drain logs to for the bound application. The syslog_drain permission is required for logs to be automatically wired to applications.
    {
      "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/:id

The :id in the URL is the identifier of a previously created binding (the same :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 Field Type Description
service_id* string ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id* string ID 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/:id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE

Response

Status Code Description
200 OK Binding was deleted. The expected response body is “{}”
410 Gone Shall be returned if the binding does not exist. The expected response body is “{}”

All other status codes will be interpreted as an error and cloud controller will inform the user that the unbind failed. The binding will remain in the cloud controller database.

We have chosen to require empty JSON in the response 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.

Deprovisioning

When a broker receives an 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/:id

The :id in the URL is the identifier of a previously provisioned instance (the same :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 Field Type Description
service_id* string ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.
plan_id* string ID 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/:id?service_id=service-id-here&plan_id=plan-id-here' -X DELETE

Response

Status Code Description
200 OK Service instance was deleted. The expected response body is “{}”
410 Gone Shall be returned if the service instance does not exist. The expected response body is “{}”

All other status codes will be interpreted as an error and cloud controller will inform the user that the deprovision failed. The service instance will remain in the cloud controller database.

We have chosen to require empty JSON in the response 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.

Broker Errors

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) as well as a JSON-encoded error payload.

This payload allows the broker to expose a message to end-user or operator. If a payload is included, only the message from the description field in the payload will be shown. If there is no payload, a generic error message containing the HTTP response code will be shown.

Response

Response Field Type Description
description string An error message explaining why the request failed. This message will likely be forwarded to the person initiating the request.

Orphans

The Cloud Controller database and a Broker are expected to store identical copies of existing instances and bindings. These two lists may potentially become inconsistent. For example, if a broker times out during a delete request, the Cloud Controller will be unsure whether that resource still exists on the broker. Cloud Controller will implement the following orphan prevention techniques:

  • If a broker fails to provision or bind an instance, the Cloud Controller will immediately issue an deprovision or unbind request.

  • If a broker fails to unbind or deprovision an instance, the Cloud Controller will periodically retry that DELETE request until it succeeds (or generates a 410). Eventually it will give up, but this technique will help clean up resources that remain when a broker fails to delete.