v3 GA service plans endpoints

[#172351417](https://www.pivotaltracker.com/story/show/172351417)

Author: pivotal-marcela-campo

docs/v2/index.html

@@ -1005,9 +1005,19 @@ <h2>
   <div class="article">
     <h2>
         <a id="service-plans" class="anchor" href="#service-plans">&#128279;</a>
-        Service Plans
+        Service Plans - Deprecated
     </h2>
 
+    <div class="panel panel-warning">
+      <div class="panel-heading" style="background-color:#f0b37e;">
+        <h3 class="panel-title" style="color:white;">Warning:</h3>
+      </div>
+      <div class="panel-body" style="background-color:#ffedcc;">
+        The V2 Service Plans resource is deprecated, please refer to the Service Plans section of the
+        <a href="http://v3-apidocs.cloudfoundry.org#service-plans" class="alert-link">V3 Docs</a>
+      </div>
+    </div>
+
     <ul>
       <li>
         <a href="service_plans/delete_a_particular_service_plans.html">Delete a Particular Service Plans</a>

…l_resources/service_plans/_delete.md.erb …s/resources/service_plans/_delete.md.erbdocs/v3/source/includes/experimental_resources/service_plans/_delete.md.erb renamed to docs/v3/source/includes/resources/service_plans/_delete.md.erb docs/v3/source/includes/experimental_resources/service_plans/_delete.md.erb renamed to docs/v3/source/includes/resources/service_plans/_delete.md.erb

@@ -18,7 +18,7 @@ Name | Type | Description
 **costs** | _array of [cost objects](#the-service-plan-cost)_ | The cost of the Service Plan as obtained from the Service Broker Catalog.
 **created_at** | _datetime_ | The time with zone when the object was created.
 **updated_at** | _datetime_ | The time with zone when the object was last updated.
-**maintenance_info** | _[maintenance_info object](#the-maintenance-info-object-for-service-plans)_ | Information about the version of this service instance.
+**maintenance_info** | _[maintenance_info object](#the-maintenance-info-object-for-service-plans)_ | Information about the version of this service plan.
 **broker_catalog** | _[broker catalog object](#the-service-plan-broker-catalog)_ | This object contains information obtained from the Service Broker Catalog.
 **schemas** | _[schemas object](#the-service-plan-schemas)_ | Schema definitions for Service Instances and Service Bindings for the Service Plan.
 **relationships.service_offering** | [_to-one relationship_](#to-one-relationships) | The Service Offering that this Service Plan relates to.

…ntal_resources/service_plans/_get.md.erb …udes/resources/service_plans/_get.md.erbdocs/v3/source/includes/experimental_resources/service_plans/_get.md.erb renamed to docs/v3/source/includes/resources/service_plans/_get.md.erb docs/v3/source/includes/experimental_resources/service_plans/_get.md.erb renamed to docs/v3/source/includes/resources/service_plans/_get.md.erb

@@ -438,6 +438,15 @@ In V2, the endpoint to apply a security group to a space only includes the lifec
 
 In V3, the endpoint to apply a security group to a space includes the lifecycle. For example to unbind a security group from the running lifecycle, one would `DELETE /v3/security_groups/:guid/relationships/running_spaces/:space_guid`.
 
+### Service Brokers in V3
+
+#### Create, Update and Delete
+
+
+In V3 these endpoints are now asynchronous. See [Asynchronous operations](#asynchronous-operations) and [Service Broker Jobs](#service-broker-jobs) for more information.
+
+Read more about the [service broker resource](#service-brokers).
+
 ### Service Offerings in V3
 
 Services endpoints are now replaced by [Service Offerings endpoints](#service-offerings) at `/v3/service_offerings`
@@ -451,32 +460,58 @@ Some services related endpoints nested in other resources have been translated t
 `GET /v2/services/:guid/service_plans` is now a filter on the `Service Plan` resource: `GET /v3/service_plans?service_offering_guids=guid`. This link can also be found in the object's `links` section.
 
 
-In V2, `service_broker_name and service_broker_guid` where top level attributes in the response. V3 returns this values only if requested using the [`fields` syntax](#fields). Refer to [Service Offerings endpoints](#service-offerings) for further information. A link to the `Service Broker` resource is included in the object's `relationships` section.  
+In V2, `service_broker_name` was returned in the response. V3 returns this value only if requested using the [`fields` syntax](#fields). Refer to [Service Offerings endpoints](#service-offerings) for further information. A link to the `Service Broker` resource is included in the object's `links` section.  
 
 The structure of the Service Offering object as well as some attribute names have changed from V2 to V3:
 
 |**V2**|**V3**|
 |---|---|
 label | name
 active | available
-bindable | services.total_service_keys
+bindable | broker_catalog.features.bindable
 extra | shareable, broker_catalog.metadata
 unique_id | broker_catalog.id
 plan_updateable | broker_catalog.features.plan_updateable
 instances_retrievable | broker_catalog.features.instances_retrievable
 bindings_retrievable | broker_catalog.features.bindings_retrievable
+service_broker_guid | relationships.service_broker.data.guid
 
 
 Read more about the [service offering resource](#service-offerings).
 
-### Service Brokers in V3
+### Service Plans in V3
 
-#### Create, Update and Delete
+Some service plans related endpoints nested in other resources have been translated to filters on `service_plans`, with the advantage that filters accept multiple values and can be combined.
 
+`GET /v2/services/:guid/service_plans` -> `GET /v3/service_plans?service_offering_guids=guid`
 
-In V3 these endpoints are now asynchronous. See [Asynchronous operations](#asynchronous-operations) and [Service Broker Jobs](#service-broker-jobs) for more information.
+Changing plan visibility to `Public` is not a PUT operation anymore. To change visibility use the [Service Plan Visibility resource](#service-plan-visibility)
+
+The structure of the Service Plan object as well as some attribute names have changed from V2 to V3:
+
+|**V2**|**V3**|
+|---|---|
+active | available
+bindable | broker_catalog.features.bindable
+extra | broker_catalog.metadata
+public | `visibility_type == 'public'` (see [Visibility types](#list-of-visibility-types))
+unique_id | broker_catalog.id
+plan_updateable | broker_catalog.features.plan_updateable
+service_instances_url |  use `service_plan_guids` or `service_plan_names` filter on [Service Instances resource](#service-instances)
+service_url | links.service_offering.href
+service_guid | relationships.service_offering.data.guid
+
+Some filters were renamed and changed to accept a list of values:
+
+|**V2**|**V3**|
+|---|---|
+service_guid | service_offering_guids
+service_instance_guid | service_instance_guids
+service_broker_guid | service_broker_guids
+unique_id | broker_catalog_ids
+
+Read more about the [service plan resource](#service-plans).
 
-Read more about the [service broker resource](#service-brokers).
 
 ### Space Quotas in V3
 

…ental_resources/service_plans/_header.md …ludes/resources/service_plans/_header.mddocs/v3/source/includes/experimental_resources/service_plans/_header.md renamed to docs/v3/source/includes/resources/service_plans/_header.md docs/v3/source/includes/experimental_resources/service_plans/_header.md renamed to docs/v3/source/includes/resources/service_plans/_header.md

@@ -253,6 +253,12 @@ includes:
   - resources/service_offerings/list
   - resources/service_offerings/update
   - resources/service_offerings/delete  
+  - resources/service_plans/header
+  - resources/service_plans/object
+  - resources/service_plans/get
+  - resources/service_plans/list
+  - resources/service_plans/update
+  - resources/service_plans/delete
   - resources/spaces/header
   - resources/spaces/object
   - resources/spaces/create
@@ -321,12 +327,6 @@ includes:
   - experimental_resources/service_bindings/get
   - experimental_resources/service_bindings/list
   - experimental_resources/service_bindings/delete
-  - experimental_resources/service_plans/header
-  - experimental_resources/service_plans/object
-  - experimental_resources/service_plans/get
-  - experimental_resources/service_plans/list
-  - experimental_resources/service_plans/update
-  - experimental_resources/service_plans/delete
   - experimental_resources/service_plan_visibility/header
   - experimental_resources/service_plan_visibility/object
   - experimental_resources/service_plan_visibility/visibility_types