Merge "Add subscription api ref"

api-ref/source/index.rst

@@ -20,3 +20,4 @@ Messaging Service API v2 (CURRENT)
 .. include:: versions.inc
 .. include:: queues.inc
 .. include:: claims.inc
+.. include:: subscription.inc

api-ref/source/parameters.yaml

@@ -22,6 +22,13 @@ claim_id:
   description: |
     The id of the claim.
 
+subscription_id_path:
+  type: string
+  in: path
+  required: True
+  description: |
+    The id of the subscription.
+
 #### variables in query ######################################################
 
 limit:
@@ -78,6 +85,35 @@ claim_grace:
     the specified grace period. If a claimed message would normally live longer
     than the grace period, its expiration is not adjusted.
 
+subscriber:
+  type: string
+  in: body
+  required: True
+  description: |
+    The ``subscriber`` attribute specifies the destination where the message
+    notify to. It has been designed to match the Internet RFC on Relative
+    Uniform Resource Locators. Zaqar now support two kinds of subscribers:
+    http/https and email. The http/https subscriber should start with
+    ``http/https``. The email subscriber should start with ``mailto``.
+
+subscription_ttl:
+  type: integer
+  in: body
+  required: false
+  description: |
+    The ``ttl`` attribute specifies how long the subscription be alive. The ttl
+    value must be great than 60 seconds. The default value is 3600 seconds.
+
+subscription_options:
+  type: dict
+  in: body
+  required: false
+  description: |
+    The ``options`` attribute specifies the extra metadata for the subscription
+    . The value must be a dict and could contain any key-value. If the
+    subscriber is "mailto". The ``options`` can contain ``from`` and
+    ``subject`` to indicate the email's author and title.
+
 #### variables in response ###################################################
 
 versions:
@@ -130,3 +166,27 @@ _default_message_ttl:
     value is the same value defined as ''max_message_ttl'' in zaqar.conf. It is
     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
+  description: |
+    A list of the subscriptions.
+
+subscription_id:
+  type: string
+  in: body
+  description: |
+    The id of the subscription.
+
+subscription_age:
+  type: integer
+  in: body
+  description: |
+    How long the subscription has be existed.
+
+subscription_source:
+  type: string
+  in: body
+  description: |
+    The queue name which the subscription is registered on.

api-ref/source/samples/subscription-create-request-http.json

@@ -0,0 +1,5 @@
+{
+    "subscriber":"http://10.229.49.117:5679",
+    "ttl":3600,
+    "options":{}
+}

api-ref/source/samples/subscription-create-request-mail.json

@@ -0,0 +1,8 @@
+{
+    "subscriber":"mailto://test@gmail.com",
+    "ttl":3600,
+    "options":{
+      "from": "Jack",
+      "subject": "Hello"
+    }
+}

api-ref/source/samples/subscription-create-response.json

@@ -0,0 +1,3 @@
+{
+  "subscription_id": "57692ab13990b48c644bb7e6"
+}

api-ref/source/samples/subscription-show-response.json

@@ -0,0 +1,10 @@
+{
+  "age": 1632,
+  "id": "576b54963990b48c644bb7e7",
+  "subscriber": "http://10.229.49.117:5679",
+  "source": "test",
+  "ttl": 3600,
+  "options": {
+    "name": "test"
+  }
+}

api-ref/source/samples/subscription-update-request.json

@@ -0,0 +1,7 @@
+{
+    "subscriber":"http://10.229.49.117:1234",
+    "ttl":360,
+    "options":{
+      "name": "test"
+    }
+}

api-ref/source/samples/subscriptions-list-response.json

@@ -0,0 +1,26 @@
+{
+  "links": [
+    {
+      "href": "/v2/queues/test/subscriptions?marker=57692ab13990b48c644bb7e6",
+      "rel": "next"
+    }
+  ],
+  "subscriptions": [
+    {
+      "age": 13,
+      "id": "57692aa63990b48c644bb7e5",
+      "subscriber": "http://10.229.49.117:5678",
+      "source": "test",
+      "ttl": 360,
+      "options": {}
+    },
+    {
+      "age": 2,
+      "id": "57692ab13990b48c644bb7e6",
+      "subscriber": "http://10.229.49.117:5679",
+      "source": "test",
+      "ttl": 360,
+      "options": {}
+    }
+  ]
+}

api-ref/source/subscription.inc

@@ -0,0 +1,225 @@
+============================
+Subscriptions(subscriptions)
+============================
+
+List Subscriptions
+==================
+
+.. rest_method::  GET /v2/queues/{queue_name}/subscriptions
+
+Lists a queue's subscriptions.
+
+This operation lists subscriptions for a queue. The subscriptions are sorted
+alphabetically by name.
+
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+
+
+Query Parameters
+~~~~~~~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - marker: marker
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - subscriptions: subscriptions
+  - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/subscriptions-list-response.json
+   :language: javascript
+
+
+Create Subscription
+===================
+
+.. rest_method::  POST /v2/queues/{queue_name}/subscriptions
+
+Creates a subscription.
+
+This operation creates a new subscription.
+
+
+Normal response codes: 201
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - subscriber: subscriber
+  - ttl: subscription_ttl
+  - options: subscription_options
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/subscription-create-request-http.json
+   :language: javascript
+
+.. literalinclude:: samples/subscription-create-request-mail.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - subscription_id: subscription_id
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/subscription-create-response.json
+   :language: javascript
+
+
+Update Subscription
+===================
+
+.. rest_method::  PATCH /v2/queues/{queue_name}/subscriptions/{subscription_id}
+
+Updates a subscription.
+
+Normal response codes: 204
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- Conflict (409)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - subscription_id: subscription_id_path
+  - subscriber: subscriber
+  - ttl: subscription_ttl
+  - options: subscription_options
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/subscription-update-request.json
+   :language: javascript
+
+
+This operation does not return a response body.
+
+
+Show Subscription Details
+=========================
+
+.. rest_method::  GET /v2/queues/{queue_name}/subscriptions/{subscription_id}
+
+Shows details for a subscription.
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - subscription_id: subscription_id_path
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - age: subscription_age
+  - id: subscription_id
+  - subscriber: subscriber
+  - source: subscription_source
+  - ttl: subscription_ttl
+  - options: subscription_options
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/subscription-show-response.json
+   :language: javascript
+
+
+Delete Subscription
+===================
+
+.. rest_method::  DELETE /v2/queues/{queue_name}/subscriptions/{subscription_id}
+
+Deletes the specified subscription.
+
+
+Normal response codes: 204
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - subscription_id: subscription_id_path
+
+
+This operation does not accept a request body and does not return a response
+body.