From 9a3b0191af06dcff28ee6c7c702c8dce7cc9a1de Mon Sep 17 00:00:00 2001 From: Fei Long Wang Date: Tue, 31 May 2016 14:31:42 +1200 Subject: [PATCH] Add Queues for api ref Change-Id: I45566944491d0ddf6d43ad60c3f97d3d7f5aa057 --- api-ref/source/index.rst | 13 +- api-ref/source/parameters.yaml | 90 +++++++ api-ref/source/queues.inc | 249 ++++++++++++++++++ .../source/samples/queue-create-request.json | 5 + .../source/samples/queue-show-response.json | 5 + .../source/samples/queue-stats-response.json | 7 + .../source/samples/queue-update-request.json | 7 + .../source/samples/queue-update-response.json | 3 + .../source/samples/queues-list-response.json | 22 ++ .../samples/versions-list-response.json | 0 api-ref/source/v2/index.rst | 20 -- api-ref/source/v2/parameters.yaml | 16 -- api-ref/source/v2/queues.inc | 0 api-ref/source/versions.inc | 38 +++ api-ref/source/versions/index.rst | 20 -- api-ref/source/versions/parameters.yaml | 8 - api-ref/source/versions/versions.inc | 35 --- 17 files changed, 432 insertions(+), 106 deletions(-) create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/queues.inc create mode 100644 api-ref/source/samples/queue-create-request.json create mode 100644 api-ref/source/samples/queue-show-response.json create mode 100644 api-ref/source/samples/queue-stats-response.json create mode 100644 api-ref/source/samples/queue-update-request.json create mode 100644 api-ref/source/samples/queue-update-response.json create mode 100644 api-ref/source/samples/queues-list-response.json rename api-ref/source/{versions => }/samples/versions-list-response.json (100%) delete mode 100644 api-ref/source/v2/index.rst delete mode 100644 api-ref/source/v2/parameters.yaml delete mode 100644 api-ref/source/v2/queues.inc create mode 100644 api-ref/source/versions.inc delete mode 100644 api-ref/source/versions/index.rst delete mode 100644 api-ref/source/versions/parameters.yaml delete mode 100644 api-ref/source/versions/versions.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 0a5db8d6..2ccdf6da 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -11,12 +11,11 @@ License for the specific language governing permissions and limitations under the License. -====================== -Messaging Service APIs -====================== +:tocdepth: 2 -.. toctree:: - :maxdepth: 1 +================================== +Messaging Service API v2 (CURRENT) +================================== - versions/index - v2/index \ No newline at end of file +.. include:: versions.inc +.. include:: queues.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 00000000..f652fca3 --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -0,0 +1,90 @@ +#### variables in header ##################################################### + +client_id: + type: UUID + in: header + description: | + A unique ID for indicating where the request come from. + +#### variables in path ####################################################### + +queue_name: + type: string + in: path + required: True + description: | + The name of the queue. + +#### variables in query ###################################################### + +limit: + type: integer + in: query + required: false + description: | + Requests a page size of items. Returns a number of items up to a limit + value. Use the ``limit`` parameter to make an initial limited request and + use the ID of the last-seen item from the response as the ``marker`` + parameter value in a subsequent limited request. + +marker: + type: string + in: query + required: false + description: | + The ID of the last-seen item. Use the ``limit`` parameter to make an + initial limited request and use the ID of the last-seen item from the + response as the ``marker`` parameter value in a subsequent limited request. + +#### variables in response ################################################### + +versions: + type: list + in: body + required: True + description: | + A list of supported major API versions. + +queues: + type: list + in: body + description: | + A list of the queues. + +links: + type: array + in: body + required: true + description: | + Links related to the queues. This is a list of dictionaries, each including + keys ``href`` and ``rel``. + +queue_metadata: + type: dict + in: body + description: | + Metadata of queue. + +_max_messages_post_size: + type: integer + in: body + required: True + description: | + The max post size of messages defined for a queue, which will effect for + any messages posted to the queue. So user can define a queue's level + cap for post size which can't bigger than the max_messages_post_size + defined in zaqar.conf. It is one of the ``reserved attributes`` of Zaqar + queues. The value will be reverted to the default value after deleting it + explicitly. + +_default_message_ttl: + type: integer + in: body + required: True + description: | + The default TTL of messages defined for a queue, which will effect for + any messages posted to the queue. So when there is no TTL defined for a + message, the queue's _default_message_ttl will be used. By default, the + value is the same value defined as ''max_message_ttl'' in zaqar.conf. It is + one of the ``reserved attributes`` of Zaqar queues. The value will be + reverted to the default value after deleting it explicitly. diff --git a/api-ref/source/queues.inc b/api-ref/source/queues.inc new file mode 100644 index 00000000..b81cc442 --- /dev/null +++ b/api-ref/source/queues.inc @@ -0,0 +1,249 @@ +=============== +Queues (queues) +=============== + +List queues +=========== + +.. rest_method:: GET /v2/queues + +Lists queues. + +A request to list queues when you have no queues in your account returns 204, +instead of 200, because there was no information to send back. + +This operation lists queues for the project. The queues are sorted +alphabetically by name. + + +Normal response codes: 200 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- ServiceUnavailable (503) + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - limit: limit + - marker: marker + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - queues: queues + - links: links + + +Response Example +---------------- + +.. literalinclude:: samples/queues-list-response.json + :language: javascript + + +Create queue +============ + +.. rest_method:: PUT /v2/queues/{queue_name} + +Creates a queue. + +This operation creates a new queue. + +The body of the request is empty. + +``queue_name`` is the name that you give to the queue. The name must not +exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, +underscores, and hyphens. + + +Normal response codes: 201, 204 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- ServiceUnavailable (503) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - queue_name: queue_name + +Request Example +--------------- + +.. literalinclude:: samples/queue-create-request.json + :language: javascript + + +This operation does not return a response body. + + +Update queue +============ + +.. rest_method:: PATCH /v2/queues/{queue_name} + +Updates a queue. + +Normal response codes: 200 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- Not Found (404) +- Conflict (409) +- ServiceUnavailable (503) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - queue_name: queue_name + +When setting the request body of updating queue, the body must be a list which +contains a series of json object which follows +https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10. + +.. note:: + + - The "Content-Type" header should be + "application/openstack-messaging-v2.0-json-patch" + + - The ''path'' must start with /metadata, for example, if the key is + ''ttl'', then the path should be /metadata/ttl + + +Request Example +--------------- + +.. literalinclude:: samples/queue-update-request.json + :language: javascript + + +Response Example +---------------- + +.. literalinclude:: samples/queue-update-response.json + :language: javascript + + +Show queue details +================== + +.. rest_method:: GET /v2/queues/{queue_name} + +Shows details for a queue. + +Normal response codes: 200 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- ServiceUnavailable (503) + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - queue_name: queue_name + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - _max_messages_post_size: _max_messages_post_size + - _default_message_ttl: _default_message_ttl + +Response Example +---------------- + +.. literalinclude:: samples/queue-show-response.json + :language: javascript + + +Delete queue +=============== + +.. rest_method:: DELETE /v2/queues/{queue_name} + +Deletes the specified queue. + +This operation immediately deletes a queue and all of its existing messages. + +``queue_name`` is the name that you give to the queue. The name must not +exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, +underscores, and hyphens. + + +Normal response codes: 204 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- ServiceUnavailable (503) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - queue_name: queue_name + +This operation does not accept a request body and does not return a response +body. + + +Get queue stats +=============== + +.. rest_method:: GET /v2/queues/{queue_name}/stats + +Returns statistics for the specified queue. + +This operation returns queue statistics, including how many messages are in +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 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- ServiceUnavailable (503) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - queue_name: queue_name + +Response Example +---------------- + +.. literalinclude:: samples/queue-stats-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/samples/queue-create-request.json b/api-ref/source/samples/queue-create-request.json new file mode 100644 index 00000000..052ea935 --- /dev/null +++ b/api-ref/source/samples/queue-create-request.json @@ -0,0 +1,5 @@ +{ + "_max_messages_post_size": 262144, + "_default_message_ttl": 3600, + "description": "Queue for international traffic billing." +} \ No newline at end of file diff --git a/api-ref/source/samples/queue-show-response.json b/api-ref/source/samples/queue-show-response.json new file mode 100644 index 00000000..2dd85e49 --- /dev/null +++ b/api-ref/source/samples/queue-show-response.json @@ -0,0 +1,5 @@ +{ + "_max_messages_post_size": 262144, + "_default_message_ttl": 3600, + "description": "Queue used for billing." +} \ No newline at end of file diff --git a/api-ref/source/samples/queue-stats-response.json b/api-ref/source/samples/queue-stats-response.json new file mode 100644 index 00000000..1bb147da --- /dev/null +++ b/api-ref/source/samples/queue-stats-response.json @@ -0,0 +1,7 @@ +{ + "messages":{ + "claimed": 10, + "total": 20, + "free": 10 + } +} \ No newline at end of file diff --git a/api-ref/source/samples/queue-update-request.json b/api-ref/source/samples/queue-update-request.json new file mode 100644 index 00000000..7723199c --- /dev/null +++ b/api-ref/source/samples/queue-update-request.json @@ -0,0 +1,7 @@ +[ + { + "op": "replace", + "path": "/metadata/max_timeout", + "value": 100 + } +] \ No newline at end of file diff --git a/api-ref/source/samples/queue-update-response.json b/api-ref/source/samples/queue-update-response.json new file mode 100644 index 00000000..2fbafcf2 --- /dev/null +++ b/api-ref/source/samples/queue-update-response.json @@ -0,0 +1,3 @@ +{ + "max_timeout": 100 +} \ No newline at end of file diff --git a/api-ref/source/samples/queues-list-response.json b/api-ref/source/samples/queues-list-response.json new file mode 100644 index 00000000..05b79bbf --- /dev/null +++ b/api-ref/source/samples/queues-list-response.json @@ -0,0 +1,22 @@ +{ + "queues":[ + { + "href":"/v2/queues/beijing", + "name":"beijing" + }, + { + "href":"/v2/queues/london", + "name":"london" + }, + { + "href":"/v2/queues/wellington", + "name":"wellington" + } + ], + "links":[ + { + "href":"/v2/queues?marker=wellington", + "rel":"next" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/versions/samples/versions-list-response.json b/api-ref/source/samples/versions-list-response.json similarity index 100% rename from api-ref/source/versions/samples/versions-list-response.json rename to api-ref/source/samples/versions-list-response.json diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst deleted file mode 100644 index 5bc8db7a..00000000 --- a/api-ref/source/v2/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -:tocdepth: 2 - -================================== -Messaging Service API v2 (CURRENT) -================================== - -.. include:: queues.inc diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml deleted file mode 100644 index 39e9e058..00000000 --- a/api-ref/source/v2/parameters.yaml +++ /dev/null @@ -1,16 +0,0 @@ -#### variables in header###################################################### - -client_id: - type: UUID - in: header - description: | - A unique ID for indicating where the request come from. - -#### variables in path ####################################################### - -queue_name: - type: string - in: path - required: True - description: | - The name of the queue. \ No newline at end of file diff --git a/api-ref/source/v2/queues.inc b/api-ref/source/v2/queues.inc deleted file mode 100644 index e69de29b..00000000 diff --git a/api-ref/source/versions.inc b/api-ref/source/versions.inc new file mode 100644 index 00000000..b507733b --- /dev/null +++ b/api-ref/source/versions.inc @@ -0,0 +1,38 @@ +============ +API Versions +============ + +The Zaqar API only supports ''major versions'' expressed in request URLs. + + +List major versions +=================== + +.. rest_method:: GET / + +Gets the home document. + +This operation gets the home document. + +The entire API is discoverable from a single starting point, the home document. To explore the entire API, you need to know only this one URI. This document is cacheable. + +The home document lets you write clients by using relational links, so clients do not have to construct their own URLs. You can click through and view the JSON doc in your browser. + +For more information about home documents, see `http://tools.ietf.org/html/draft-nottingham-json-home-02 `__. + + +Normal response codes: 300 +Error response codes: serviceUnavailable (503) + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - versions: versions + +Response Example +---------------- + +.. literalinclude:: samples/versions-list-response.json + :language: javascript diff --git a/api-ref/source/versions/index.rst b/api-ref/source/versions/index.rst deleted file mode 100644 index 14b0e5a7..00000000 --- a/api-ref/source/versions/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -:tocdepth: 2 - -========================== -Messaging Service Versions -========================== - -.. include:: versions.inc \ No newline at end of file diff --git a/api-ref/source/versions/parameters.yaml b/api-ref/source/versions/parameters.yaml deleted file mode 100644 index 2a94a34c..00000000 --- a/api-ref/source/versions/parameters.yaml +++ /dev/null @@ -1,8 +0,0 @@ -#### variables in response#################################################### - -versions: - type: list - in: body - required: True - description: | - A list of supported major API versions. \ No newline at end of file diff --git a/api-ref/source/versions/versions.inc b/api-ref/source/versions/versions.inc deleted file mode 100644 index 5907fe66..00000000 --- a/api-ref/source/versions/versions.inc +++ /dev/null @@ -1,35 +0,0 @@ -============ -API Versions -============ - -Concepts -======== - -The Zaqar API only supports ''major versions'' expressed in request URLs. - - -List Major Versions -=================== - -.. rest_method:: GET / - -This fetches all the information about all known major API versions in -the deployment. Links to more specific information will be provided -for each API version. - - -Normal response codes: 300 -Error response codes: serviceUnavailable (503) - -Response Parameters -------------------- - -.. rest_parameters:: parameters.yaml - - - versions: versions - -Response Example ----------------- - -.. literalinclude:: samples/versions-list-response.json - :language: javascript