From 8d54d2c2b6ed1ec6c72acffc936cabb0f98fd0be Mon Sep 17 00:00:00 2001 From: liuyamin Date: Fri, 23 Mar 2018 17:34:12 +0800 Subject: [PATCH] Use rest_status_code for api-ref response codes Rather than our freeform way of listing response codes in our api-ref, we should be using the os-api-ref extension option to get nicely formatted response code listings. https://docs.openstack.org/os-api-ref/latest/usage.html#rest-status-code Change-Id: I70b5f0c20089d0eaa201ab9d9bbf9ec1464ec636 --- api-ref/source/claims.inc | 70 ++++++++++++------ api-ref/source/flavors.inc | 81 +++++++++++++------- api-ref/source/health.inc | 26 +++++-- api-ref/source/messages.inc | 103 +++++++++++++++++--------- api-ref/source/pools.inc | 75 ++++++++++++------- api-ref/source/queues.inc | 127 +++++++++++++++++++++----------- api-ref/source/status.yaml | 58 +++++++++++++++ api-ref/source/subscription.inc | 79 +++++++++++++------- api-ref/source/versions.inc | 12 ++- 9 files changed, 437 insertions(+), 194 deletions(-) create mode 100644 api-ref/source/status.yaml diff --git a/api-ref/source/claims.inc b/api-ref/source/claims.inc index 24fe3b25e..b00cebcdc 100644 --- a/api-ref/source/claims.inc +++ b/api-ref/source/claims.inc @@ -50,14 +50,20 @@ live period, its expiration is not adjusted. -Normal response codes: 201, 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized(401) -- Forbidden(403) -- itemNotFound(404) -- ServiceUnavailable(503) + - 201 + - 204 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + - 503 Request Parameters ------------------ @@ -101,14 +107,19 @@ with malformed IDs or claims that are not found by ID are ignored. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized(401) -- Forbidden(403) -- itemNotFound(404) -- ServiceUnavailable(503) + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + - 503 Request Parameters ------------------ @@ -147,14 +158,19 @@ TTL). The server resets the age of the claim and applies the new TTL. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized(401) -- Forbidden(403) -- itemNotFound(404) -- ServiceUnavailable(503) + - 204 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + - 503 Request Parameters ------------------ @@ -195,14 +211,20 @@ to other workers. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized(401) -- Forbidden(403) -- itemNotFound(404) -- ServiceUnavailable(503) + - 204 + + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + - 503 Request Parameters ------------------ diff --git a/api-ref/source/flavors.inc b/api-ref/source/flavors.inc index d607ff741..bbffcd662 100644 --- a/api-ref/source/flavors.inc +++ b/api-ref/source/flavors.inc @@ -18,12 +18,17 @@ This operation lists flavors for the project. The flavors are sorted alphabetically by name. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized (401) -- Forbidden (403) + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 Query Parameters ----------------- @@ -64,13 +69,18 @@ exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. -Normal response codes: 201 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Forbidden (403) + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 Request Parameters @@ -98,15 +108,20 @@ Update flavor Updates a flavor. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Forbidden (403) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 503 Request Parameters @@ -139,15 +154,20 @@ Show flavor details Shows details for a flavor. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Forbidden (403) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + - 503 Request Parameters ------------------ @@ -187,13 +207,18 @@ exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized (401) -- Forbidden (403) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 503 Request Parameters diff --git a/api-ref/source/health.inc b/api-ref/source/health.inc index fba0ad0fd..5a9cd38e2 100644 --- a/api-ref/source/health.inc +++ b/api-ref/source/health.inc @@ -16,11 +16,16 @@ A request to ping Zaqar server when server is working returns 204, otherwise returns 503. This can be a handy API for end user to check if the messaging service is in working status. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 503 This operation does not accept a request body and does not return a response @@ -42,13 +47,18 @@ default, there is no pool created. Then the response body will only contain the ``catalog_reachable``. Otherwise, the response body will have ``catalog_reachable`` and the health status for each pool. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized (401) -- Forbidden (403) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 503 Response Parameters diff --git a/api-ref/source/messages.inc b/api-ref/source/messages.inc index aea3a77cf..fd727ae22 100644 --- a/api-ref/source/messages.inc +++ b/api-ref/source/messages.inc @@ -56,14 +56,19 @@ to allow for flexibility in storage implementations. The ``delay`` attribute specifies how long the message can be claimed. The value of ``delay`` must be between 0 and 900 seconds (15 mins). -Normal response codes: 201 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters ------------------ @@ -115,14 +120,19 @@ implementations. Results are ordered by age, oldest message first. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters @@ -179,14 +189,19 @@ is the hash digest of the ``body``, default algorithm is MD5. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters @@ -229,14 +244,20 @@ contain at least one id and not greater than ``max_messages_per_page`` in conf. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 204 + + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters @@ -274,14 +295,19 @@ hash digest of the ``body``, default algorithm is MD5. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters @@ -321,14 +347,19 @@ fails. You can only delete claimed messages by providing an appropriate -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request ------- diff --git a/api-ref/source/pools.inc b/api-ref/source/pools.inc index e24dd9204..af4131477 100644 --- a/api-ref/source/pools.inc +++ b/api-ref/source/pools.inc @@ -19,12 +19,17 @@ This operation lists pools for the project. The pools are sorted alphabetically by name. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Not Found (404) -- Unauthorized (401) + - 200 + +.. rest_status_code:: error status.yaml + + - 404 + - 401 Query Parameters ----------------- @@ -65,13 +70,18 @@ exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. -Normal response codes: 201 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Conflict (409) + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 409 Request Parameters @@ -102,14 +112,19 @@ Update pool Updates a pool. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters @@ -145,13 +160,18 @@ Show pool details Shows details for a pool. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters ------------------ @@ -192,13 +212,18 @@ exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- Unauthorized (401) -- Forbidden (403) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 503 Request Parameters diff --git a/api-ref/source/queues.inc b/api-ref/source/queues.inc index 5b5764e61..61d01a530 100644 --- a/api-ref/source/queues.inc +++ b/api-ref/source/queues.inc @@ -24,13 +24,18 @@ This operation lists queues for the project. The queues are sorted alphabetically by name. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters ------------------ @@ -79,13 +84,19 @@ _dead_letter_queue_messages_ttl. In order to support the delayed queues, now add a metadata ``_default_message_delay``. -Normal response codes: 201, 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 201 + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters @@ -119,15 +130,20 @@ Update queue Updates a queue. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- Conflict (409) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 409 + - 503 Request Parameters @@ -171,13 +187,18 @@ Show queue details Shows details for a queue. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters ------------------ @@ -216,13 +237,18 @@ exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters @@ -249,13 +275,18 @@ the queue, categorized by status. If the value of the ``total`` attribute is 0, then ``oldest`` and ``newest`` message statistics are not included in the response. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters @@ -289,14 +320,19 @@ Create a pre-signed URL for a given queue. to try a DoS on that pool. Therefore, whenever a pre-signed URL is created, if a pool doesn't exist, it needs to be created. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 503 Request Parameters @@ -346,13 +382,18 @@ Purge particular resource of the queue. Now Zaqar supports to purge "messages" and "subscriptions" resource from a queue. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters diff --git a/api-ref/source/status.yaml b/api-ref/source/status.yaml new file mode 100644 index 000000000..3242f27f7 --- /dev/null +++ b/api-ref/source/status.yaml @@ -0,0 +1,58 @@ + 200: + default: | + Request was successful. + 201: + default: | + Request has been fulfilled and new resource created. + 202: + default: | + Request is accepted, but processing may take some time. + 203: + default: | + Returned information is not full set, but a subset. + 204: + default: | + Request fulfilled but service does not return anything. + 300: + default: | + The resource corresponds to more than one representation. + 400: + default: | + Some content in the request was invalid. + 401: + default: | + User must authenticate before making a request. + 403: + default: | + Policy does not allow current user to do this operation. + 404: + default: | + The requested resource could not be found. + 405: + default: | + Method is not valid for this endpoint and resource. + 409: + default: | + This resource has an action in progress that would conflict with this request. + 413: + default: | + This operation cannot be completed. + 415: + default: | + The entity of the request is in a format not supported by the requested + resource for the method. + 422: + default: | + The entity of the request is in a format not processable by the requested + resource for the method. + 500: + default: | + Something went wrong with the service which prevents it from fulfilling + the request. + 501: + default: | + The service does not have the functionality required to fulfill this + request. + 503: + default: | + The service cannot handle the request right now. diff --git a/api-ref/source/subscription.inc b/api-ref/source/subscription.inc index d357521cd..dc09762d2 100644 --- a/api-ref/source/subscription.inc +++ b/api-ref/source/subscription.inc @@ -17,13 +17,18 @@ This operation lists subscriptions for a queue. The subscriptions are sorted alphabetically by name. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters @@ -69,13 +74,18 @@ Creates a subscription. This operation creates a new subscription. -Normal response codes: 201 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters @@ -121,15 +131,20 @@ Update Subscription Updates a subscription. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- Not Found (404) -- Conflict (409) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 404 + - 409 + - 503 Request Parameters @@ -161,13 +176,18 @@ Show Subscription Details Shows details for a subscription. -Normal response codes: 200 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters @@ -207,13 +227,18 @@ Delete Subscription Deletes the specified subscription. -Normal response codes: 204 +Response codes +-------------- -Error response codes: +.. rest_status_code:: success status.yaml -- BadRequest (400) -- Unauthorized (401) -- ServiceUnavailable (503) + - 204 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 503 Request Parameters diff --git a/api-ref/source/versions.inc b/api-ref/source/versions.inc index b8a671792..1ea9e6888 100644 --- a/api-ref/source/versions.inc +++ b/api-ref/source/versions.inc @@ -21,10 +21,16 @@ The home document lets you write clients by using relational links, so clients d For more information about home documents, see `http://tools.ietf.org/html/draft-nottingham-json-home-02 `__. -Normal response codes: 300 -Error response codes: +Response codes +-------------- -- serviceUnavailable (503) +.. rest_status_code:: success status.yaml + + - 300 + +.. rest_status_code:: error status.yaml + + - 503 Response Parameters -------------------