openstack
/
deb-zaqar
Code Issues Proposed changes

Merge "Add Queues for api ref"

This commit is contained in:
Jenkins 2016-06-15 03:57:12 +00:00 committed by Gerrit Code Review
parent a2eaac82d4 9a3b0191af
commit 43255acc3a
17 changed files with 432 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
api-ref/source/index.rst
View File

@ -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
.. include:: versions.inc
.. include:: queues.inc

90
api-ref/source/parameters.yaml Normal file
View File

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

249
api-ref/source/queues.inc Normal file
View File

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

5
api-ref/source/samples/queue-create-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"_max_messages_post_size": 262144,
"_default_message_ttl": 3600,
"description": "Queue for international traffic billing."
}

5
api-ref/source/samples/queue-show-response.json Normal file
View File

@ -0,0 +1,5 @@
{
"_max_messages_post_size": 262144,
"_default_message_ttl": 3600,
"description": "Queue used for billing."
}

7
api-ref/source/samples/queue-stats-response.json Normal file
View File

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

7
api-ref/source/samples/queue-update-request.json Normal file
View File

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

3
api-ref/source/samples/queue-update-response.json Normal file
View File

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

22
api-ref/source/samples/queues-list-response.json Normal file
View File

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

0
api-ref/source/versions/samples/versions-list-response.json → api-ref/source/samples/versions-list-response.json
View File

20
api-ref/source/v2/index.rst
View File

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

16
api-ref/source/v2/parameters.yaml
View File

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

0
api-ref/source/v2/queues.inc
View File

38
api-ref/source/versions.inc Normal file
View File

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

20
api-ref/source/versions/index.rst
View File

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

8
api-ref/source/versions/parameters.yaml
View File

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

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

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