Tweak api-ref doc for services/endpoints

This patch reorders the sections about services and endpoints which were
previously interleaved randomly. After the reordering, all services APIs
appear before all endpoint APIs so browsing through the APIs would be
much easier. This patch aslo changes the representations of status codes
using the new stanza in os-api-ref.

Change-Id: I89aabd3d9a336f5f6f65aaca51353f2d23b4cb2a

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
+You can create, list, show details for, update, and delete endpoints.
-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
+--------------
 
-Error response codes: 413,405,404,403,401,400,503
+.. rest_status_code:: success status.yaml
 
-Request
+   - 200
--------
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+
+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
+--------------
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+.. rest_status_code:: success status.yaml
 
-Request
+   - 201
--------
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 409
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -102,208 +120,6 @@ Response Parameters
    - description: service_description
 
 
-Show endpoint details
-=====================
-
-.. rest_method::  GET /v3/endpoints/{endpoint_id}
-
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
-
-Shows details for an endpoint.
-
-Normal response codes: 200
-
-Error response codes: 413,405,404,403,401,400,503
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - endpoint_id: endpoint_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
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/admin/endpoint-show-response.json
-   :language: javascript
-
-
-Update endpoint
-===============
-
-.. rest_method::  PATCH /v3/endpoints/{endpoint_id}
-
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
-
-Updates an endpoint.
-
-Normal response codes: 200
-
-Error response codes: 413,415,405,404,403,401,400,503,409
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - 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/endpoint-update-request.json
-   :language: javascript
-
-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
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/admin/endpoint-update-response.json
-   :language: javascript
-
-
-Delete endpoint
-===============
-
-.. rest_method::  DELETE /v3/endpoints/{endpoint_id}
-
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
-
-Deletes an endpoint.
-
-Normal response codes: 204
-
-Error response codes: 413,415,405,404,403,401,400,503,409
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - endpoint_id: endpoint_id_path
-
-
-List endpoints
-==============
-
-.. rest_method::  GET /v3/endpoints
-
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
-
-Lists all available endpoints.
-
-Normal response codes: 200
-
-Error response codes: 413,405,404,403,401,400,503
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - interface: interface_query
-   - service_id: service_id_query
-
-Response Parameters
--------------------
-
-.. rest_parameters:: parameters.yaml
-
-   - region_id: region_id
-   - links: endpoints_links
-   - url: endpoint_url
-   - region: endpoint_region
-   - enabled: endpoint_enabled
-   - interface: endpoint_region
-   - service_id: service_id
-   - endpoints: endpoints
-   - id: endpoint_id
-
-Response Example
-----------------
-
-.. literalinclude:: ./samples/admin/endpoints-list-response.json
-   :language: javascript
-
-
-Create endpoint
-===============
-
-.. rest_method::  POST /v3/endpoints
-
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
-
-Creates an endpoint.
-
-Normal response codes: 201
-
-Error response codes: 413,415,405,404,403,401,400,503,409
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - endpoint: endpoint
-   - url: endpoint_url
-   - enabled: endpoint_enabled_notRequired
-   - interface: endpoint_interface
-   - service_id: service_id
-   - region_id: region_id
-
-Request Example
----------------
-
-.. literalinclude:: ./samples/admin/endpoint-create-request.json
-   :language: javascript
-
-Response Parameters
--------------------
-
-.. rest_parameters:: parameters.yaml
-
-   - endpoint: endpoint
-   - links: endpoint_links
-   - url: endpoint_url
-   - region: endpoint_region
-   - enabled: endpoint_enabled
-   - interface: endpoint_interface
-   - service_id: service_id
-   - id: endpoint_id
-   - region_id: region_id
-
-
 Show service details
 ====================
 
@@ -313,12 +129,22 @@ Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/service``
 
 Shows details for a service.
 
-Normal response codes: 200
+Response Codes
+--------------
 
-Error response codes: 413,405,404,403,401,400,503
+.. rest_status_code:: success status.yaml
 
-Request
+   - 200
--------
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -356,12 +182,23 @@ The request body is the same as the create service request body,
 except that you include only those attributes that you want to
 update.
 
-Normal response codes: 200
+Response Codes
+--------------
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+.. rest_status_code:: success status.yaml
 
-Request
+   - 200
--------
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
@@ -410,13 +247,275 @@ 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.
 
-Normal response codes: 204
+Response Codes
+--------------
 
-Error response codes: 413,415,405,404,403,401,400,503,409
+.. rest_status_code:: success status.yaml
 
-Request
+   - 204
--------
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
 
 .. rest_parameters:: parameters.yaml
 
    - service_id: service_id_path
+
+
+List endpoints
+==============
+
+.. rest_method::  GET /v3/endpoints
+
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
+
+Lists all available endpoints.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - interface: interface_query
+   - service_id: service_id_query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - region_id: region_id
+   - links: endpoints_links
+   - url: endpoint_url
+   - region: endpoint_region
+   - enabled: endpoint_enabled
+   - interface: endpoint_region
+   - service_id: service_id
+   - endpoints: endpoints
+   - id: endpoint_id
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/endpoints-list-response.json
+   :language: javascript
+
+
+Create endpoint
+===============
+
+.. rest_method::  POST /v3/endpoints
+
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
+
+Creates an endpoint.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 409
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint: endpoint
+   - url: endpoint_url
+   - enabled: endpoint_enabled_notRequired
+   - interface: endpoint_interface
+   - service_id: service_id
+   - region_id: region_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/admin/endpoint-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint: endpoint
+   - links: endpoint_links
+   - url: endpoint_url
+   - region: endpoint_region
+   - enabled: endpoint_enabled
+   - interface: endpoint_interface
+   - service_id: service_id
+   - id: endpoint_id
+   - region_id: region_id
+
+
+Show endpoint details
+=====================
+
+.. rest_method::  GET /v3/endpoints/{endpoint_id}
+
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoints``
+
+Shows details for an endpoint.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint_id: endpoint_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
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/endpoint-show-response.json
+   :language: javascript
+
+
+Update endpoint
+===============
+
+.. rest_method::  PATCH /v3/endpoints/{endpoint_id}
+
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
+
+Updates an endpoint.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+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
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/admin/endpoint-update-request.json
+   :language: javascript
+
+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
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/endpoint-update-response.json
+   :language: javascript
+
+
+Delete endpoint
+===============
+
+.. rest_method::  DELETE /v3/endpoints/{endpoint_id}
+
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/endpoint``
+
+Deletes an endpoint.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint_id: endpoint_id_path