Merge "Add Queues for api ref"

api-ref/source/index.rst

@@ -11,12 +11,11 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-======================
+:tocdepth: 2
-Messaging Service APIs
-======================
 
-.. toctree::
+==================================
-   :maxdepth: 1
+Messaging Service API v2 (CURRENT)
+==================================
 
-   versions/index
+.. include:: versions.inc
-   v2/index
+.. include:: queues.inc

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.

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

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."
+}

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."
+}

api-ref/source/samples/queue-stats-response.json

@@ -0,0 +1,7 @@
+{
+    "messages":{
+         "claimed": 10,
+         "total": 20,
+         "free": 10
+    }
+}

api-ref/source/samples/queue-update-request.json

@@ -0,0 +1,7 @@
+[
+    {
+        "op": "replace",
+        "path": "/metadata/max_timeout",
+        "value": 100
+    }
+]

api-ref/source/samples/queue-update-response.json

@@ -0,0 +1,3 @@
+{
+    "max_timeout": 100
+}

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"
+      }
+   ]
+}

api-ref/source/v2/index.rst

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

api-ref/source/v2/parameters.yaml

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

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

api-ref/source/versions/index.rst

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

api-ref/source/versions/parameters.yaml

@@ -1,8 +0,0 @@
-#### variables in response####################################################
-
-versions:
-  type: list
-  in: body
-  required: True
-  description: |
-    A list of supported major API versions.

api-ref/source/versions/versions.inc

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