openstack/zaqar
Code Issues Proposed changes

Use rest_status_code for api-ref response codes

Browse Source 
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
This commit is contained in:
liuyamin 2018-03-23 17:34:12 +08:00
parent 480c29a21c
commit 8d54d2c2b6
9 changed files with 437 additions and 194 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
api-ref/source/claims.inc
View File

@ -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
------------------

81
api-ref/source/flavors.inc
View File

@ -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

26
api-ref/source/health.inc
View File

@ -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

103
api-ref/source/messages.inc
View File

@ -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
-------

75
api-ref/source/pools.inc
View File

@ -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

127
api-ref/source/queues.inc
View File

@ -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

58
api-ref/source/status.yaml Normal file
View File

@ -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.

79
api-ref/source/subscription.inc
View File

@ -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

12
api-ref/source/versions.inc
View File

@ -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 <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
-------------------