commit 2cb835375c45463f5dcf44f10f39943d37adb070
Author: Giorgos Korfiatis <gkorf@grnet.gr>
Date:   Tue Apr 30 12:14:09 2013 +0300

    Update quota API docs

diff --git a/docs/quota-api-guide.rst b/docs/quota-api-guide.rst
index 15ef073..fe4acd1 100644
--- a/docs/quota-api-guide.rst
+++ b/docs/quota-api-guide.rst
@@ -1,18 +1,27 @@
 Resources
 ---------
 
+Synnefo services offer *resources* to their users. Each type of resource is
+registered in Astakos with a unique name. By convention, these names start
+with the service name, e.g. ``cyclades.vm`` is a resource representing the
+virtual machines offered by Cyclades.
+
+
 Get Resource List
 .................
 
 **GET** /astakos/api/resources
 
-**Normal Response Code**: 200
+This call returns a description for each resource available in the system.
+The response consists of a dictionary, indexed by the resource name, which
+contains a number of attributes for each resource.
 
-**Error Response Codes**:
+**Response Codes**:
 
 ======  =====================
 Status  Description
 ======  =====================
+200     Success
 500     Internal Server Error
 ======  =====================
 
@@ -36,6 +45,15 @@ Status  Description
 Quotas
 ------
 
+The system specifies user quotas for each available resource. Resources
+can be allocated from various sources. By default, users get resources
+from a single source, called ``system``. For each combination of user,
+source, and resource, the quota system keeps track of the maximum allowed
+value (limit) and the current actual usage. The former is controlled by
+the policy defined in Astakos; the latter is updated by the services that
+actually implement the resource each time an allocation or deallocation
+takes place.
+
 Get Quotas
 ..........
 
@@ -47,13 +65,19 @@ Request Header Name   Value
 X-Auth-Token          User authentication token
 ====================  =========================
 
-**Normal Response Code**: 200
+A user can query their resources with this call. It returns in a nested
+dictionary structure, for each source and resource, three indicators.
+``limit`` and ``usage`` are as explained above. ``pending`` is related to the
+commissioning system explained below. Roughly, if ``pending`` is non zero,
+this indicates that some resource allocation process has started but not
+finished properly.
 
-**Error Response Codes**:
+**Response Codes**:
 
 ======  ============================
 Status  Description
 ======  ============================
+200     Success
 401     Unauthorized (Missing token)
 500     Internal Server Error
 ======  ============================
@@ -101,15 +125,19 @@ Request Header Name   Value
 X-Auth-Token          Service authentication token
 ====================  ============================
 
-Optional GET parameter: ?user=<uuid>
+A service can query the quotas for all resources related to it. By default,
+it returns the quotas for all users, in the format explained above, indexed
+by the user identifier (UUID).
+
+Use the GET parameter ``?user=<uuid>`` to query for a single user.
 
-**Normal Response Code**: 200
 
-**Error Response Codes**:
+**Response Codes**:
 
 ======  ============================
 Status  Description
 ======  ============================
+200     Success
 401     Unauthorized (Missing token)
 500     Internal Server Error
 ======  ============================
@@ -150,6 +178,18 @@ Status  Description
 Commissions
 -----------
 
+When a resource allocation is about to take place, the service that performs
+this operation can query the quota system to find out whether the planned
+allocation would surpass some defined limits. If this is not the case, the
+quota system registers this pending allocation. Upon the actual allocation
+of resources, the service informs the quota system to definitely update the
+usage.
+
+Thus, changing quotas consists of two steps: in the first, the service
+issues a *commission*, indicating which extra resources will be given to
+particular users; in the second, it finalizes the commission by *accepting*
+it (or *rejecting*, if the allocation did not actually take place).
+
 Issue Commission
 ................
 
@@ -161,20 +201,17 @@ Request Header Name   Value
 X-Auth-Token          Service authentication token
 ====================  ============================
 
-**Normal Response Code**: 201
+A service issues a commission by providing a list of *provisions*, i.e.
+the intended allocation for a particular user (in general, ``holder``),
+``source``, and ``resource`` combination.
 
-**Error Response Codes**:
+The request body consists of a JSON dict (as in the example below), which
+apart from the provisions list can also contain the following optional
+fields:
 
-======  =======================================================
-Status  Description
-======  =======================================================
-400     Commission failed due to invalid input data
-401     Unauthorized (Missing token)
-404     Cannot find one of the target holdings
-413     A quantity fell below zero in one of the holdings
-413     A quantity exceeded the capacity in one of the holdings
-500     Internal Server Error
-======  =======================================================
+ * ``name``: An optional description of the operation
+ * ``force``: Succeed even if a limit is surpassed
+ * ``auto_accept``: Perform the two steps at once
 
 **Example Request**:
 
@@ -200,6 +237,30 @@ Status  Description
       ]
   }
 
+**Response Codes**:
+
+======  =======================================================
+Status  Description
+======  =======================================================
+201     Success
+400     Commission failed due to invalid input data
+401     Unauthorized (Missing token)
+404     Cannot find one of the target holdings
+413     A quantity fell below zero in one of the holdings
+413     A quantity exceeded the capacity in one of the holdings
+500     Internal Server Error
+======  =======================================================
+
+On a successful commission, the call responds with a ``serial``, an identifier
+for the commission. On failure, in the case of ``overLimit`` (413) or
+``itemNotFound`` (404), the returned cloudFault contains an extra field
+``data`` with additional application-specific information. It contains at
+least the ``provision`` that is to blame and the actual ``name`` of the
+exception raised. In case of ``NoCapacityError``, ``limit`` and ``usage`` are
+also included; in case of ``NoQuantityError`` (that is, when attempting to
+release a value greater than what is registered), the ``available`` quantity
+is provided.
+
 **Example Successful Response**:
 
 .. code-block:: javascript
@@ -241,13 +302,17 @@ Request Header Name   Value
 X-Auth-Token          Service authentication token
 ====================  ============================
 
-**Normal Response Code**: 200
+The service can query the quota system for all *pending* commissions
+initiated by itself, that is, all commissions that have been issued
+but not accepted or rejected (see below). The call responds with the list
+of the serials of all pending commissions.
 
-**Error Response Codes**:
+**Response Codes**:
 
 ======  ============================
 Status  Description
 ======  ============================
+200     Success
 401     Unauthorized (Missing token)
 500     Internal Server Error
 ======  ============================
@@ -269,13 +334,14 @@ Request Header Name   Value
 X-Auth-Token          Service authentication token
 ====================  ============================
 
-**Normal Response Code**: 200
+This call allows a service to retrieve information for a pending commission.
 
-**Error Response Codes**:
+**Response Codes**:
 
 ======  ============================
 Status  Description
 ======  ============================
+200     Success
 401     Unauthorized (Missing token)
 404     Commission Not Found
 500     Internal Server Error
@@ -316,17 +382,13 @@ Request Header Name   Value
 X-Auth-Token          Service authentication token
 ====================  ============================
 
-**Normal Response Code**: 200
+With this call a service can *accept* or *reject* a pending commission, that
+is, finalize the registered usage or undo commission issued.
+The system guarantees that a commission can always be later accepted
+or rejected, no matter what other commissions have taken place in the meantime.
 
-**Error Response Codes**:
-
-======  ============================
-Status  Description
-======  ============================
-401     Unauthorized (Missing token)
-404     Commission Not Found
-500     Internal Server Error
-======  ============================
+To accept, include in the request body a field indexed by ``accept``;
+likewise for rejecting.
 
 **Example Requests**:
 
@@ -340,6 +402,17 @@ Status  Description
       "reject": ""
   }
 
+**Response Codes**:
+
+======  ============================
+Status  Description
+======  ============================
+200     Success
+401     Unauthorized (Missing token)
+404     Commission Not Found
+500     Internal Server Error
+======  ============================
+
 Accept or Reject Multiple Commissions
 .....................................
 
@@ -351,16 +424,9 @@ Request Header Name   Value
 X-Auth-Token          Service authentication token
 ====================  ============================
 
-**Normal Response Code**: 200
-
-**Error Response Codes**:
-
-======  ============================
-Status  Description
-======  ============================
-401     Unauthorized (Missing token)
-500     Internal Server Error
-======  ============================
+This allows to accept and reject multiple commissions in the same time,
+by including the list of serials to accept and the list of serials to reject
+in the request body.
 
 **Example Request**:
 
@@ -371,6 +437,21 @@ Status  Description
       "reject": [56, 58, 59]
   }
 
+The response includes the list of serials that have been actually
+``accepted`` or ``rejected`` and those that ``failed``. The latter
+consists of a list of pairs. The first element of the pair is a serial
+that failed, the second element is a cloudFault describing the failure.
+
+**Response Codes**:
+
+======  ============================
+Status  Description
+======  ============================
+200     Success
+401     Unauthorized (Missing token)
+500     Internal Server Error
+======  ============================
+
 **Example Successful Response**:
 
 .. code-block:: javascript
