Merge "Tweak api-ref doc for services/endpoints"10.0.0.0rc1

1 files changed, 226 insertions, 127 deletions

diff --git a/api-ref/source/v3/service-catalog.inc b/api-ref/source/v3/service-catalog.inc
index dc3a77b7d..e9a43c0f3 100644
--- a/api-ref/source/v3/service-catalog.inc
+++ b/api-ref/source/v3/service-catalog.inc
@@ -5,7 +5,7 @@
 ===============================
 
 A service is an OpenStack web service that you can access through a
-URL, or endpoint.
+URL, i.e. an endpoint.
 
 A service catalog lists the services that are available to the
 caller based upon the current authorization.
@@ -15,8 +15,7 @@ services. When you create or update a service, you can enable the
 service, which causes it and its endpoints to appear in the service
 catalog.
 
-You can create, list, show details for, update, and delete
-endpoints.
+You can create, list, show details for, update, and delete endpoints.
 
 
 List services
@@ -28,12 +27,21 @@ Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/services`
 
 Lists all services.
 
-Normal response codes: 200
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
 
-Error response codes: 413,405,404,403,401,400,503
+   - 400
+   - 401
+   - 403
 
-Request
--------
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -68,12 +76,22 @@ Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/services`
 
 Creates a service.
 
-Normal response codes: 201
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
+
+.. rest_status_code:: error status.yaml
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+   - 400
+   - 401
+   - 403
+   - 409
 
-Request
--------
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -102,75 +120,99 @@ Response Parameters
    - description: service_description
 
 
-Show endpoint details
-=====================
+Show service details
+====================
 
-.. rest_method::  GET /v3/endpoints/{endpoint_id}
+.. rest_method::  GET /v3/services/{service_id}
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/service``
 
-Shows details for an endpoint.
+Shows details for a service.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
 
-Normal response codes: 200
+   - 200
 
-Error response codes: 413,405,404,403,401,400,503
+.. rest_status_code:: error status.yaml
 
-Request
--------
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - endpoint_id: endpoint_id_path
+   - service_id: service_id_path
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - endpoint: endpoint
-   - name: endpoint_name
-   - links: endpoint_links
-   - url: endpoint_url
-   - region: endpoint_region
-   - interface: endpoint_interface
-   - service_id: service_id
+   - name: service_name
+   - service: service
+   - links: service_links
+   - type: service_type
+   - id: service_id
+   - description: service_description
 
 Response Example
 ----------------
 
-.. literalinclude:: ./samples/admin/endpoint-show-response.json
+.. literalinclude:: ./samples/admin/service-show-response.json
    :language: javascript
 
 
-Update endpoint
-===============
+Update service
+==============
 
-.. rest_method::  PATCH /v3/endpoints/{endpoint_id}
+.. rest_method::  PATCH /v3/services/{service_id}
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/services``
 
-Updates an endpoint.
+Updates a service.
+
+The request body is the same as the create service request body,
+except that you include only those attributes that you want to
+update.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
 
-Normal response codes: 200
+.. rest_status_code:: error status.yaml
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
 
-Request
--------
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - endpoint: endpoint
-   - url: endpoint_url
-   - region: endpoint_region
-   - interface: endpoint_interface
-   - service_id: service_id
-   - endpoint_id: endpoint_id_path
+   - type: service_type
+   - enabled: service_enabled_notRequired
+   - description: service_description_notRequired
+   - service: service
+   - name: service_name
+   - service_id: service_id_path
 
 Request Example
 ---------------
 
-.. literalinclude:: ./samples/admin/endpoint-update-request.json
+.. literalinclude:: ./samples/admin/service-update-request.json
    :language: javascript
 
 Response Parameters
@@ -178,40 +220,53 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - endpoint: endpoint
-   - id: endpoint_id
-   - links: endpoint_links
-   - url: endpoint_url
-   - region: endpoint_region
-   - interface: endpoint_interface
-   - service_id: service_id
+   - name: service_name
+   - service: service
+   - links: service_links
+   - type: service_type
+   - id: service_id
+   - description: service_description
 
 Response Example
 ----------------
 
-.. literalinclude:: ./samples/admin/endpoint-update-response.json
+.. literalinclude:: ./samples/admin/service-update-response.json
    :language: javascript
 
 
-Delete endpoint
-===============
+Delete service
+==============
 
-.. rest_method::  DELETE /v3/endpoints/{endpoint_id}
+.. rest_method::  DELETE /v3/services/{service_id}
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/service``
 
-Deletes an endpoint.
+Deletes a service.
+
+If you try to delete a service that still has associated endpoints,
+this call either deletes all associated endpoints or fails until
+all endpoints are deleted.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 204
 
-Normal response codes: 204
+.. rest_status_code:: error status.yaml
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+   - 400
+   - 401
+   - 403
+   - 404
 
-Request
--------
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - endpoint_id: endpoint_id_path
+   - service_id: service_id_path
 
 
 List endpoints
@@ -223,12 +278,21 @@ Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints
 
 Lists all available endpoints.
 
-Normal response codes: 200
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
 
-Error response codes: 413,405,404,403,401,400,503
+.. rest_status_code:: error status.yaml
 
-Request
--------
+   - 400
+   - 401
+   - 403
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -266,12 +330,22 @@ Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints
 
 Creates an endpoint.
 
-Normal response codes: 201
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+.. rest_status_code:: error status.yaml
 
-Request
--------
+   - 400
+   - 401
+   - 403
+   - 409
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -304,78 +378,96 @@ Response Parameters
    - region_id: region_id
 
 
-Show service details
-====================
+Show endpoint details
+=====================
 
-.. rest_method::  GET /v3/services/{service_id}
+.. rest_method::  GET /v3/endpoints/{endpoint_id}
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/service``
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
 
-Shows details for a service.
+Shows details for an endpoint.
+
+Response Codes
+--------------
 
-Normal response codes: 200
+.. rest_status_code:: success status.yaml
 
-Error response codes: 413,405,404,403,401,400,503
+   - 200
 
-Request
--------
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - service_id: service_id_path
+   - endpoint_id: endpoint_id_path
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - name: service_name
-   - service: service
-   - links: service_links
-   - type: service_type
-   - id: service_id
-   - description: service_description
+   - endpoint: endpoint
+   - name: endpoint_name
+   - links: endpoint_links
+   - url: endpoint_url
+   - region: endpoint_region
+   - interface: endpoint_interface
+   - service_id: service_id
 
 Response Example
 ----------------
 
-.. literalinclude:: ./samples/admin/service-show-response.json
+.. literalinclude:: ./samples/admin/endpoint-show-response.json
    :language: javascript
 
 
-Update service
-==============
+Update endpoint
+===============
 
-.. rest_method::  PATCH /v3/services/{service_id}
+.. rest_method::  PATCH /v3/endpoints/{endpoint_id}
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/services``
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
 
-Updates a service.
+Updates an endpoint.
 
-The request body is the same as the create service request body,
-except that you include only those attributes that you want to
-update.
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
 
-Normal response codes: 200
+   - 200
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+.. rest_status_code:: error status.yaml
 
-Request
--------
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - type: service_type
-   - enabled: service_enabled_notRequired
-   - description: service_description_notRequired
-   - service: service
-   - name: service_name
-   - service_id: service_id_path
+   - endpoint: endpoint
+   - url: endpoint_url
+   - region: endpoint_region
+   - interface: endpoint_interface
+   - service_id: service_id
+   - endpoint_id: endpoint_id_path
 
 Request Example
 ---------------
 
-.. literalinclude:: ./samples/admin/service-update-request.json
+.. literalinclude:: ./samples/admin/endpoint-update-request.json
    :language: javascript
 
 Response Parameters
@@ -383,40 +475,47 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - name: service_name
-   - service: service
-   - links: service_links
-   - type: service_type
-   - id: service_id
-   - description: service_description
+   - endpoint: endpoint
+   - id: endpoint_id
+   - links: endpoint_links
+   - url: endpoint_url
+   - region: endpoint_region
+   - interface: endpoint_interface
+   - service_id: service_id
 
 Response Example
 ----------------
 
-.. literalinclude:: ./samples/admin/service-update-response.json
+.. literalinclude:: ./samples/admin/endpoint-update-response.json
    :language: javascript
 
 
-Delete service
-==============
+Delete endpoint
+===============
 
-.. rest_method::  DELETE /v3/services/{service_id}
+.. rest_method::  DELETE /v3/endpoints/{endpoint_id}
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/service``
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
 
-Deletes a service.
+Deletes an endpoint.
 
-If you try to delete a service that still has associated endpoints,
-this call either deletes all associated endpoints or fails until
-all endpoints are deleted.
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
 
-Normal response codes: 204
+   - 204
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+.. rest_status_code:: error status.yaml
 
-Request
--------
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - service_id: service_id_path
+   - endpoint_id: endpoint_id_path