From 4d4faabf148a95583e909e9fe07cafebc5765871 Mon Sep 17 00:00:00 2001 From: tengqm Date: Fri, 9 Sep 2016 02:11:22 -0400 Subject: [PATCH] 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 | 549 +++++++++++++++----------- 1 file changed, 324 insertions(+), 225 deletions(-) diff --git a/api-ref/source/v3/service-catalog.inc b/api-ref/source/v3/service-catalog.inc index dc3a77b7d7..e9a43c0f31 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 +-------------- -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