Merge "Add some descriptions for resources in API Ref"

api-ref/source/claims.inc

@@ -1,6 +1,8 @@
 ===============
 Claims (claims)
 ===============
+Claim is a mechanism to mark messages so that other workers will not process
+the same message.
 
 Claim messages
 ==============

api-ref/source/health.inc

@@ -1,6 +1,9 @@
 ===============
 Health (health)
 ===============
+With health API, user or operator can get a general idea about the status of
+Zaqar server. Those information can be used for basic validation, performance
+checking, etc.
 
 Ping
 ====

api-ref/source/messages.inc

@@ -1,6 +1,12 @@
 ===================
 Messages (messages)
 ===================
+Message is sent through a queue and exists until it is deleted by a recipient
+or automatically by the system based on a TTL (time-to-live) value.
+
+All message-related operations require Client-Id to be included in the headers.
+This is to ensure that messages are not echoed back to the client that posted
+them unless the client explicitly requests this.
 
 Post Message
 ============

api-ref/source/pools.inc

@@ -1,9 +1,15 @@
 ===============
 Pools (pools)
 ===============
+If pooling is enabled, queuing service uses multiple queues databases in order
+to scale horizontally. A pool (queues database) can be added any time without
+stopping the service. Each pool has a weight that is assigned during the
+creation time but can be changed later. Pooling is done by queue which
+indicates that all messages for a particular queue can be found in the same
+pool (queues database).
 
 List pools
-===========
+==========
 
 .. rest_method:: GET /v2/pools
 

api-ref/source/queues.inc

@@ -1,6 +1,14 @@
 ===============
 Queues (queues)
 ===============
+Queue is a logical entity that groups messages. Ideally a queue is created per
+work type. For example, if you want to compress files, you would create a queue
+dedicated for this job. Any application that reads from this queue would only
+compress files.
+
+Nowadays, queue in Zaqar is most like a topic, it's created lazily. User can
+post messages to a queue before creating the queue. Zaqar will create the
+queue/topic automatically.
 
 List queues
 ===========

api-ref/source/subscription.inc

@@ -1,6 +1,10 @@
 ============================
 Subscriptions(subscriptions)
 ============================
+Subscriptions are relationships between queue/topic and the targeted
+subscribers. After created subscriptions for a particular subscriber, like an
+email or a webhook, then when new messages posted to the queue, the subscriber
+will be notified automatically.
 
 List Subscriptions
 ==================