diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index f9bde2803..c020459c6 100644 --- a/api-ref/source/parameters.yaml +++ b/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 diff --git a/api-ref/source/queues.inc b/api-ref/source/queues.inc index b81cc442d..b57899d54 100644 --- a/api-ref/source/queues.inc +++ b/api-ref/source/queues.inc @@ -246,4 +246,66 @@ Response Example ---------------- .. literalinclude:: samples/queue-stats-response.json - :language: javascript \ No newline at end of file + :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 diff --git a/api-ref/source/samples/queue-pre-signed-request.json b/api-ref/source/samples/queue-pre-signed-request.json new file mode 100644 index 000000000..2b56f79da --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/api-ref/source/samples/queue-pre-signed-response.json b/api-ref/source/samples/queue-pre-signed-response.json new file mode 100644 index 000000000..400cfecff --- /dev/null +++ b/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" +}