Add `Pre-signed queue' api ref

Change-Id: I7a7dfc3a30f3c9d754410fa96ec94b86f1b92ffa

api-ref/source/parameters.yaml

@@ -167,6 +167,7 @@ _default_message_ttl:
     one of the ``reserved attributes`` of Zaqar queues. The value will be
     reverted to the default value after deleting it explicitly.
 
+
 subscriptions:
   type: list
   in: body
@@ -219,3 +220,44 @@ operation_status:
     indicate if the actions was successful or not. Ref may contain the
     information if the succeeded is False, otherwise it's null.
 
+project_id:
+  type: string
+  in: body
+  required: True
+  description: |
+    The ID of current project/tenant.
+
+pre_signed_queue_paths:
+  type: list
+  in: body
+  required: True
+  description: |
+    A list of paths the pre-signed queue can support. It could be a set of
+    ``messages``, ``subscriptions``, ``claims``.
+
+pre_signed_queue_methods:
+  type: list
+  in: body
+  required: True
+  description: |
+    A list of HTTP methods. The HTTP method(s) this URL was created for. By
+    selecting the HTTP method, it’s possible to give either read or read/write
+    access to a specific resource.
+
+pre_signed_queue_expires:
+  type: string
+  in: body
+  required: True
+  description: |
+    The time to indicate when the pre-signed will be expired.
+
+pre_signed_queue_signature:
+  type: list
+  in: body
+  required: True
+  description: |
+    The signature is generated after create the pre-signed URL. It can be
+    consumed by adding below to HTTP headers:
+
+    URL-Signature: 6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799
+    URL-Expires: 2015-05-31T19:00:17Z

api-ref/source/queues.inc

@@ -246,4 +246,66 @@ Response Example
 ----------------
 
 .. literalinclude:: samples/queue-stats-response.json
-   :language: javascript
+   :language: javascript
+
+
+Pre-signed queue
+================
+
+.. rest_method::  POST /v2/queues/{queue_name}/share
+
+Create a pre-signed URL for a given queue.
+
+.. 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
+   URL. This is not a big issues in cases where there’s just 1 pool. However,
+   if there’s a deployment using more than 1 type of pool, the lazily created
+   queue may end up in an undesired pool and it’d be possible for an attacker
+   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
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - paths: pre_signed_queue_paths
+  - methods: pre_signed_queue_methods
+  - expires: pre_signed_queue_expires
+
+Request Example
+---------------
+
+.. literalinclude:: samples/queue-pre-signed-request.json
+   :language: javascript
+
+
+Response Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - project: project_id
+  - paths: pre_signed_queue_paths
+  - methods: pre_signed_queue_methods
+  - expires: pre_signed_queue_expires
+  - signature: pre_signed_queue_signature
+
+Response Example
+----------------
+
+.. literalinclude:: samples/queue-pre-signed-response.json
+   :language: javascript

api-ref/source/samples/queue-pre-signed-request.json

@@ -0,0 +1,5 @@
+{
+  "paths": ["messages", "claims", "subscriptions"],
+  "methods": ["GET", "POST", "PUT", "PATCH"],
+  "expires": "2016-09-01T00:00:00"
+}

api-ref/source/samples/queue-pre-signed-response.json

@@ -0,0 +1,16 @@
+{
+    "project": "2887aabf368046a3bb0070f1c0413470",
+    "paths": [
+        "/v2/queues/test/messages",
+        "/v2/queues/test/claims"
+        "/v2/queues/test/subscriptions"
+    ],
+    "expires": "2016-09-01T00:00:00",
+    "methods": [
+        "GET",
+        "PATCH",
+        "POST",
+        "PUT"
+    ],
+    "signature": "6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799"
+}