Commit afb8048e authored by Giorgos Korfiatis's avatar Giorgos Korfiatis
Browse files

Update quota API docs

parent 09684f9f
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment