anchor.diff:  
   ### <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#add-broker) to make your services and plans available to end users.
  +Once you've implemented the first endpoint `GET /v2/catalog` above, you'll want
  +to [register the broker with CF](managing-service-brokers.html#add-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:
  +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 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.
  -
  +* 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`
   
  -**In this API, 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.
  +**In this API, 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.
   
   <table>
   <thead>
  
positive.code: ---
  title: Service Broker API
  ---
  
  ## <a id='changelog'></a>Document Changelog ##
  
  * [v2 API Change Log](v2-api-changelog.html)
  
  ## <a id='versions'></a>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 current brokers are upgraded.
  
  
  <div style="width:50%">
    <table>
  
negative.code: 
  * Addition of app_guid as a required field to the bind endpoint.
  
  ## <a id='dependencies'></a>Dependencies ##
  
  v2.1 of the services API has been supported since final build 152 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("../images/svcs-api/v2services.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.1`
  
  ## <a id='authentication'></a>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 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.
  
  ### CLI-friendly vs web UI-friendly strings
  
  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.
  
  ### Request ###
  
  ##### Route #####
  `GET /v2/catalog`
  
  ##### cURL #####
  <pre class="terminal">
   $ curl http://username:password@broker-url/v2/catalog
  </pre>
  
  ### Response ###
  
  <table>
  
  