From b41802c3ad483acb63fcec3dd054941747f595c5 Mon Sep 17 00:00:00 2001
From: wanghao <sxmatch1986@gmail.com>
Date: Tue, 20 Dec 2016 17:07:32 +0800
Subject: [PATCH] Add API ref of purging queue

Now Zaqar has supported to qurge queue,
add api ref for it.

Partially Implements: blueprint purge-queue

Change-Id: If9f4f5aec92bf8c4bd5e9e0f0ca833bc8214b121
---
 api-ref/source/parameters.yaml                |  8 ++++
 api-ref/source/queues.inc                     | 38 ++++++++++++++++++-
 .../source/samples/purge-queue-request.json   |  3 ++
 3 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 api-ref/source/samples/purge-queue-request.json

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 43df7a387..e4a523157 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -213,6 +213,14 @@ flavor_pool_group:
     The ``pool_group`` attribute specifies the name of the pool group
     this flavor sits on top of.
 
+resource_types:
+  type: list
+  in: body
+  required: false
+  description: |
+    The ``resource_types`` attribute allows user to purge particular resource
+    of the queue.
+
 #### variables in response ###################################################
 
 versions:
diff --git a/api-ref/source/queues.inc b/api-ref/source/queues.inc
index 5637cc430..26fd14bc0 100644
--- a/api-ref/source/queues.inc
+++ b/api-ref/source/queues.inc
@@ -264,7 +264,7 @@ Pre-signed queue
 
 Create a pre-signed URL for a given queue.
 
-.. note:
+.. note::
 
    In the case of pre-signed URLs, the queue cannot be created lazily. This
    is to prevent cases where queues are deleted and users still have a valid
@@ -317,3 +317,39 @@ Response Example
 
 .. literalinclude:: samples/queue-pre-signed-response.json
    :language: javascript
+
+
+Purge queue
+===========
+
+.. rest_method:: POST /v2/queues/{queue_name}/purge
+
+Purge particular resource of the queue.
+
+.. note::
+
+   Now Zaqar supports to purge "messages" and "subscriptions" resource from
+   a queue.
+
+Normal response codes: 204
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - resource_types: resource_types
+
+Request Example
+---------------
+
+.. literalinclude:: samples/purge-queue-request.json
+   :language: javascript
diff --git a/api-ref/source/samples/purge-queue-request.json b/api-ref/source/samples/purge-queue-request.json
new file mode 100644
index 000000000..8722c822f
--- /dev/null
+++ b/api-ref/source/samples/purge-queue-request.json
@@ -0,0 +1,3 @@
+{
+    "resource_types": ["messages", "subscriptions"]
+}
\ No newline at end of file