From fabc0b1bd731395b39a039adb763a51f8019c737 Mon Sep 17 00:00:00 2001 From: wanghao Date: Mon, 4 Jul 2016 19:37:29 +0800 Subject: [PATCH] Add pools api ref Change-Id: Ib66eef4af791fd854966c7d99067c84541661b6c --- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 69 +++++- api-ref/source/pools.inc | 205 ++++++++++++++++++ .../source/samples/pool-create-request.json | 8 + .../source/samples/pool-list-response.json | 24 ++ .../source/samples/pool-show-response.json | 7 + .../source/samples/pool-update-request.json | 8 + .../source/samples/pool-update-response.json | 7 + 8 files changed, 328 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/pools.inc create mode 100644 api-ref/source/samples/pool-create-request.json create mode 100644 api-ref/source/samples/pool-list-response.json create mode 100644 api-ref/source/samples/pool-show-response.json create mode 100644 api-ref/source/samples/pool-update-request.json create mode 100644 api-ref/source/samples/pool-update-response.json diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index b9b685162..b0b7fd01c 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -22,3 +22,4 @@ Messaging Service API v2 (CURRENT) .. include:: claims.inc .. include:: subscription.inc .. include:: health.inc +.. include:: pools.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index c020459c6..18ad803b7 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -29,6 +29,13 @@ subscription_id_path: description: | The id of the subscription. +pool_name_path: + type: string + in: path + required: True + description: + The name of the pool. + #### variables in query ###################################################### limit: @@ -114,6 +121,41 @@ subscription_options: subscriber is "mailto". The ``options`` can contain ``from`` and ``subject`` to indicate the email's author and title. +pool_weight: + type: integer + in: body + required: true + description: | + The ``weight`` attribute specifies the likelihood that this pool will be + selected for the next queue allocation. The value must be an integer + greater than -1. + +pool_uri: + type: string + in: body + required: true + description: | + The ``uri`` attribute specifies a connection string compatible with a + storage client (e.g., pymongo) attempting to connect to that pool. + +pool_group: + type: string + in: body + required: false + description: | + The ``group`` attribute specifies a tag to given to more than one pool + so that it keeps user remind the purpose/capabilities of all pools that + falls under that group. + +pool_options: + type: dict + in: body + required: false + description: | + The ``options`` attribute gives storage-specific options used by storage + driver implementations. The value must be a dict and valid key-value come + from the registered options for a given storage backend. + #### variables in response ################################################### versions: @@ -167,7 +209,6 @@ _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 @@ -261,3 +302,29 @@ pre_signed_queue_signature: URL-Signature: 6a63d63242ebd18c3518871dda6fdcb6273db2672c599bf985469241e9a1c799 URL-Expires: 2015-05-31T19:00:17Z + +pools: + type: list + in: body + description: | + A list of the pools. + +pool_href: + type: string + in: body + description: | + The url of the pool. + +pool_name: + type: string + in: body + description: | + The name of the pool. + +pool_links: + type: array + in: body + required: true + description: | + Links related to the pools. This is a list of dictionaries, each including + keys ``href`` and ``rel``. diff --git a/api-ref/source/pools.inc b/api-ref/source/pools.inc new file mode 100644 index 000000000..45fab54f3 --- /dev/null +++ b/api-ref/source/pools.inc @@ -0,0 +1,205 @@ +=============== +Pools (pools) +=============== + +List pools +=========== + +.. rest_method:: GET /v2/pools + +Lists pools. + +This operation lists pools for the project. The pools are sorted +alphabetically by name. + + +Normal response codes: 200 + +Error response codes: + +- Not Found (404) +- Unauthorized (401) + +Query Parameters +----------------- + +.. rest_parameters:: parameters.yaml + + - limit: limit + - marker: marker + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - pools: pools + - links: pool_links + + +Response Example +---------------- + +.. literalinclude:: samples/pool-list-response.json + :language: javascript + + +Create pool +============ + +.. rest_method:: PUT /v2/pools/{pool_name} + +Creates a pool. + +This operation creates a new pool. + +``pool_name`` is the name that you give to the pool. 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 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- Conflict (409) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - pool_name: pool_name_path + - weight: pool_weight + - uri: pool_uri + - group: pool_group + - options: pool_options + +Request Example +--------------- + +.. literalinclude:: samples/pool-create-request.json + :language: javascript + + +This operation does not return a response body. + + +Update pool +============ + +.. rest_method:: PATCH /v2/pools/{pool_name} + +Updates a pool. + +Normal response codes: 200 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- Not Found (404) +- ServiceUnavailable (503) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - pool_name: pool_name_path + - weight: pool_weight + - uri: pool_uri + - group: pool_group + - options: pool_options + + +Request Example +--------------- + +.. literalinclude:: samples/pool-update-request.json + :language: javascript + + +Response Example +---------------- + +.. literalinclude:: samples/pool-update-response.json + :language: javascript + + +Show pool details +================== + +.. rest_method:: GET /v2/pools/{pool_name} + +Shows details for a pool. + +Normal response codes: 200 + +Error response codes: + +- BadRequest (400) +- Unauthorized (401) +- ServiceUnavailable (503) + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - pool_name: pool_name_path + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - name: pool_name + - weight: pool_weight + - uri: pool_uri + - group: pool_group + - href: pool_href + +Response Example +---------------- + +.. literalinclude:: samples/pool-show-response.json + :language: javascript + + +Delete pool +=============== + +.. rest_method:: DELETE /v2/pools/{pool_name} + +Deletes the specified pool. + +This operation immediately deletes a pool. + +``pool_name`` is the name that you give to the pool. 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: + +- Unauthorized (401) +- Forbidden (403) +- ServiceUnavailable (503) + + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - pool_name: pool_name_path + +This operation does not accept a request body and does not return a response +body. diff --git a/api-ref/source/samples/pool-create-request.json b/api-ref/source/samples/pool-create-request.json new file mode 100644 index 000000000..5c1ea6602 --- /dev/null +++ b/api-ref/source/samples/pool-create-request.json @@ -0,0 +1,8 @@ +{ + "weight": 100, + "uri": "mongodb://127.0.0.1:27017", + "options":{ + "max_retry_sleep": 1 + }, + "group": "poolgroup" +} \ No newline at end of file diff --git a/api-ref/source/samples/pool-list-response.json b/api-ref/source/samples/pool-list-response.json new file mode 100644 index 000000000..572630f6f --- /dev/null +++ b/api-ref/source/samples/pool-list-response.json @@ -0,0 +1,24 @@ +{ + "pools": [ + { + "href": "/v2/pools/test_pool1", + "group": "poolgroup", + "name": "test_pool1", + "weight": 60, + "uri": "mongodb://192.168.1.10:27017" + }, + { + "href": "/v2/pools/test_pool2", + "group": "poolgroup", + "name": "test_pool2", + "weight": 40, + "uri": "mongodb://192.168.1.20:27017" + } + ], + "links": [ + { + "href": "/v2/pools?marker=test_pool2", + "rel": "next" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/pool-show-response.json b/api-ref/source/samples/pool-show-response.json new file mode 100644 index 000000000..f267ebf9d --- /dev/null +++ b/api-ref/source/samples/pool-show-response.json @@ -0,0 +1,7 @@ +{ + "href": "/v2/pools/test_pool", + "group": "testpoolgroup", + "name": "test_pool", + "weight": 100, + "uri": "mongodb://127.0.0.1:27017" +} \ No newline at end of file diff --git a/api-ref/source/samples/pool-update-request.json b/api-ref/source/samples/pool-update-request.json new file mode 100644 index 000000000..397be023d --- /dev/null +++ b/api-ref/source/samples/pool-update-request.json @@ -0,0 +1,8 @@ +{ + "weight": 60, + "uri": "mongodb://127.0.0.1:27017", + "options":{ + "max_retry_sleep": 1 + }, + "group": "newpoolgroup" +} \ No newline at end of file diff --git a/api-ref/source/samples/pool-update-response.json b/api-ref/source/samples/pool-update-response.json new file mode 100644 index 000000000..b3f410d68 --- /dev/null +++ b/api-ref/source/samples/pool-update-response.json @@ -0,0 +1,7 @@ +{ + "href": "/v2/pools/test_pool", + "group": "newpoolgroup", + "name": "test_pool", + "weight": 60, + "uri": "mongodb://127.0.0.1:27017" +} \ No newline at end of file