api-v2.2.html.md.erb

---
title: Service Broker API v2.2
owner: Services API
---

<strong><%= modified_date %></strong>

## <a id='changelog'></a>Document Changelog ##

[v2 API Change Log](v2-api-changelog.html)

<%= partial "version_table.html" %>

## <a id='changes'></a>Changes ##

### <a id='change-policy'></a>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.

### <a id='api-changes-since-v2-1'></a>Changes Since v2.1 ###

The key change from v2.1 to v2.2 of the Services API is:

* Addition of `free` as an optional field for a service plan in the broker catalog.

## <a id='dependencies'></a>Dependencies ##

v2.2 of the services API has been supported since final build 164 of
[cf-release](https://github.com/cloudfoundry/cf-release/).

## <a id='api-overview'></a>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("v2services-new.png", :width =>"960", :height =>"720", :style => 'background-color:#fff') %>

## <a id='api-version-header'></a>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.2`

## <a id='authentication'></a>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 they are invalid.
Cloud Controller supports connecting to a broker using SSL if additional
security is desired.

## <a id='catalog-mgmt'></a>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 should 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 which 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 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.
If there are provisioned instances, the plan will be marked “inactive” and will
no longer be visible in the marketplace catalog or be provisionable.
Cloud Controller will then delete services that do not have associated plans
from the database.

### Request ###

##### Route #####
`GET /v2/catalog`

##### cURL #####
<pre class="terminal">
 $ curl -H "X-Broker-API-Version: 2.2" http://username:password@broker-url/v2/catalog
</pre>

### Response ###

<table border="1" class="nice">
<thead>
<tr>
  <th>Status Code</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>200 OK</td>
  <td>The expected response body is below</td>
</tr>
</tbody>
</table>

##### 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 camelcase with spaces and punctuation supported.

<table border="1" class="nice">

<thead>
<tr>
  <th>Response field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>services*</td>
  <td>array-of-objects</td>
  <td>Schema of service objects defined below:</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;id*</td>
  <td>string</td>
  <td>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. </td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;name*</td>
  <td>string</td>
  <td>The CLI-friendly name of the service that will appear in the catalog. All lowercase, no spaces.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;description*</td>
  <td>string</td>
  <td>A short description of the service that will appear in the catalog.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;bindable*</td>
  <td>boolean</td>
  <td>Whether the service can be bound to applications.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;tags</td>
  <td>array-of-strings</td>
  <td>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. E.g. mysql, relational, redis, key-value, caching, messaging, amqp.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;metadata</td>
  <td>object</td>
  <td>A list of metadata for a service offering. For more information, see <a href="catalog-metadata.html">Service Metadata</a>.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;requires</td>
  <td>array-of-strings</td>
  <td>A list of permissions that the user would have to give the service, if they provision it. The only permission currently supported is <tt>syslog_drain</tt>; for more info see <a href="app-log-streaming.html">Application Log Streaming</a>.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;plans*</td>
  <td>array-of-objects
</td>
  <td>A list of plans for this service, schema defined below:</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id*</td>
  <td>string</td>
  <td>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.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name*</td>
  <td>string</td>
  <td>The CLI-friendly name of the plan that will appear in the catalog. All lowercase, no spaces.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;description*</td>
  <td>string</td>
  <td>A short description of the service that will appear in the catalog.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;metadata</td>
  <td>object</td>
  <td>A list of metadata for a service plan. For more information, see <a href="catalog-metadata.html">Service Metadata</a>.</td>
</tr>
<tr>
  <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free</td>
  <td>boolean</td>
  <td>This field allows the plan to be limited by the non_basic_services_allowed field in a Cloud Foundry Quota, see <a href="http://docs.cloudfoundry.org/running/managing-cf/quota-plans.html">Quota Plans</a>. Default: true</td>
</tr>
</tbody>
</table>

\* Fields with an asterisk are required.

<pre class="terminal">
{
  "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
    }]
  }]
}
</pre>

### <a id='create-broker'></a>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.

## <a id='provisioning'></a>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`

<p class="note"><strong>Note</strong>: The <code>:instance_id</code> 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.</p>

##### Body #####

<table border="1" class="nice">
<thead>
<tr>
  <th>Request field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>service_id*</td>
  <td>string</td>
  <td>The ID of the service within the catalog above. While not strictly necessary, some brokers might make use of this ID.</td>
</tr>
<tr>
  <td>plan_id*</td>
  <td>string</td>
  <td>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.</td>
</tr>
<tr>
  <td>organization_guid*</td>
  <td>string</td>
  <td>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.</td>
</tr>
<tr>
  <td>space_guid*</td>
  <td>string</td>
  <td>Similar to organization_guid, but for the space.</td>
</tr>
</tbody>
</table>

<pre class="terminal">
{
  "service_id":        "service-guid-here",
  "plan_id":           "plan-guid-here",
  "organization_guid": "org-guid-here",
  "space_guid":        "space-guid-here"
}
</pre>

##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url/v2/service_instances/:instance_id -d '{
  "service_id":        "service-guid-here",
  "plan_id":           "plan-guid-here",
  "organization_guid": "org-guid-here",
  "space_guid":        "space-guid-here"
}' -X PUT  -H "X-Broker-API-Version: 2.2" -H "Content-Type: application/json"
</pre>

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

### Response ###

<table border="1" class="nice">
<thead>
<tr>
  <th>Status Code</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>201 Created</td>
  <td>Service instance has been created. The expected response body is below.</td>
</tr>
<tr>
  <td>200 OK</td>
  <td>
    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.
  </td>
</tr>
<tr>
  <td>409 Conflict</td>
  <td>Should be returned if the requested service instance already exists. The expected response body is "{}", though the description field can be used to return a user-facing error message, as described in <a href="#broker-errors">Broker Errors</a>.</td>
</tr>
</tbody>
</table>

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

<table border="1" class="nice">
<thead>
<tr>
  <th>Response field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>dashboard_url</td>
  <td>string</td>
  <td>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 <a href="dashboard-sso.html">Dashboard Single Sign-On</a>.</td>
</tr>
</tboby>
</table>

<pre class="terminal">
{
 "dashboard_url": "http://mongomgmthost/databases/9189kdfsk0vfnku"
}
</pre>

## <a id='binding'></a>Binding ##

<p class="note"><strong>Note</strong>: Not all services must be bindable --- some deliver value just from being provisioned. Brokers that offer services that are not bindable should declare them as such using `bindable: false` in the [Catalog](#catalog-mgmt). Brokers that do not offer any bindable services do not need to implement the endpoint for bind requests.</p>

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](binding-credentials.html).

In addition, the bind operation can enable streaming of application logs from Cloud Foundry to a consuming service instance. For details, see [Application Log Streaming](app-log-streaming.html).

### Request ###

##### Route #####
`PUT /v2/service_instances/:instance_id/service_bindings/:binding_id`

<p class="note"><strong>Note</strong>: The <code>:binding_id</code> of a service binding is provided by the Cloud Controller. <code>:instance_id</code> is the ID of a previously-provisioned service instance; <code>:binding_id</code> will be used for future unbind requests, so the broker must use it to correlate the resource it creates.</p>

##### Body #####

<table border="1" class="nice">
<thead>
<tr>
  <th>Request Field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>service_id*</td>
  <td>string</td>
  <td>ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.</td>
</tr>
<tr>
  <td>plan_id*</td>
  <td>string</td>
  <td>ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.</td>
</tr>
<tr>
  <td>app_guid*</td>
  <td>string</td>
  <td>GUID of the application that you want to bind your service to.</td>
</tr>
</tbody>
</table>

<pre class="terminal">
{
  "plan_id": "plan-guid-here",
  "service_id": "service-guid-here",
  "app_guid": "app-guid-here"
}
</pre>

##### cURL #####
<pre class="terminal">
$ 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"
}' -X PUT  -H "X-Broker-API-Version: 2.2" -H "Content-Type: application/json"
</pre>

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 ###

<table border="1" class="nice">
<thead>
<tr>
  <th>Status Code</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>201 Created</td>
  <td>Binding has been created. The expected response body is below.</td>
</tr>
<tr>
  <td>200 OK</td>
  <td>
    May be returned if the binding already exists and the requested parameters are identical to the existing binding.
    The expected response body is below.
  </td>
</tr>
<tr>
  <td>409 Conflict</td>
  <td>Should 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 <a href="#broker-errors">Broker Errors</a>.</td>
</tr>
</tbody>
</table>

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

<table border="1" class="nice">
<thead>
<tr>
  <th>Response Field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>credentials</td>
  <td>object</td>
  <td>A free-form hash of credentials that the bound application can use to access the service. For more information, see <a href="binding-credentials.html">Binding Credentials</a>.</td>
</tr>
<tr>
  <td>syslog_drain_url</td>
  <td>string</td>
  <td>A URL to which Cloud Foundry should drain logs for the bound application. <code>requires:syslog_drain</code> must be declared in the <a href="#catalog-mgmt">catalog endpoint</a> or Cloud Foundry will consider the response invalid. For details, see <a href="app-log-streaming.html">Application Log Streaming</a>.</td>
</tr>
</tbody>
</table>

<pre class="terminal">
    {
      "credentials": {
        "uri": "mysql://mysqluser:pass@mysqlhost:3306/dbname",
        "username": "mysqluser",
        "password": "pass",
        "host": "mysqlhost",
        "port": 3306,
        "database": "dbname"
      }
    }
</pre>

## <a id='unbinding'></a>Unbinding ##

<p class="note"><strong>Note</strong>: Brokers that do not provide any bindable services do not need to implement the endpoint for unbind requests.</p>

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.

<table border="1" class="nice">
<thead>
<tr>
  <th>Query-String Field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>service_id*</td>
  <td>string</td>
  <td>ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID.</td>
</tr>
<tr>
  <td>plan_id*</td>
  <td>string</td>
  <td>ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.</td>
</tr>
</tbody>
</table>

##### cURL #####
<pre class="terminal">
$ 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.2"
</pre>

### Response ###

<table border="1" class="nice">
<thead>
<tr>
  <th>Status Code</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>200 OK</td>
  <td>Binding was deleted. The expected response body is "{}"</td>
</tr>
<tr>
  <td>410 Gone</td>
  <td>Should be returned if the binding does not exist. The expected response body is "{}"</td>
</tr>
</tbody>
</table>

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

## <a id='deprovisioning'></a>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.

<table border="1" class="nice">
<thead>
<tr>
  <th>Query-String Field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>service_id*</td>
  <td>string</td>
  <td>ID of the service from the catalog. While not strictly necessary, some brokers might make use of this ID. </td>
</tr>
<tr>
  <td>plan_id*</td>
  <td>string</td>
  <td>ID of the plan from the catalog. While not strictly necessary, some brokers might make use of this ID.</td>
</tr>
</tbody>
</table>

##### cURL #####
<pre class="terminal">
$ 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.2"
</pre>

### Response ###

<table border="1" class="nice">
<thead>
<tr>
  <th>Status Code</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>200 OK</td>
  <td>Service instance was deleted. The expected response body is "{}"</td>
</tr>
<tr>
  <td>410 Gone</td>
  <td>Should be returned if the service instance does not exist. The expected response body is "{}"</td>
</tr>
</tbody>
</table>

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

## <a id='broker-errors'></a>Broker Errors ##

### Response ###

When a broker fails to perform any requested operation, unless it fails with a
well-defined HTTP response code listed above (like 410 on delete), it 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. If empty JSON is returned in the body `"{}"`, a generic message containing the HTTP response code returned by the broker will be displayed to the requestor.

<table border="1" class="nice">
<thead>
<tr>
  <th>Response Field</th>
  <th>Type</th>
  <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
  <td>description</td>
  <td>string</td>
  <td>An error message explaining why the request failed. This message will likely be forwarded to the person initiating the request.
</td>
</tr>
</tbody>
</table>

<pre class="terminal">
{
  "description": "Something went wrong. Please contact support at http://support.example.com."
}
</pre>

## <a id='orphans'></a>Orphans ##

The Cloud Controller and Broker are expected to store identical copies of existing instances and bindings. These two lists can potentially become inconsistent if the broker doesn't return a response before the request times out (typically 60 seconds). For example, if a broker doesn't return a response to a provision request before Cloud Controller times out, the broker may eventually succeed where Cloud Controller considered this a failure. This results in an orphan instance on the service side.