Add pools api ref

Change-Id: Ib66eef4af791fd854966c7d99067c84541661b6c

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

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

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.

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"
+}

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

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"
+}

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"
+}

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"
+}