Statistics
| Branch: | Tag: | Revision:

root / docs / quota-api-guide.rst @ a1d0bacb

History | View | Annotate | Download (13.2 kB)

1 b32b5995 Giorgos Korfiatis
Resources
2 b32b5995 Giorgos Korfiatis
---------
3 b32b5995 Giorgos Korfiatis
4 2cb83537 Giorgos Korfiatis
Synnefo services offer *resources* to their users. Each type of resource is
5 2cb83537 Giorgos Korfiatis
registered in Astakos with a unique name. By convention, these names start
6 2cb83537 Giorgos Korfiatis
with the service name, e.g. ``cyclades.vm`` is a resource representing the
7 2cb83537 Giorgos Korfiatis
virtual machines offered by Cyclades.
8 2cb83537 Giorgos Korfiatis
9 2cb83537 Giorgos Korfiatis
10 b32b5995 Giorgos Korfiatis
Get Resource List
11 b32b5995 Giorgos Korfiatis
.................
12 b32b5995 Giorgos Korfiatis
13 7421af4a Giorgos Korfiatis
**GET** /account/v1.0/resources
14 b32b5995 Giorgos Korfiatis
15 2cb83537 Giorgos Korfiatis
This call returns a description for each resource available in the system.
16 2cb83537 Giorgos Korfiatis
The response consists of a dictionary, indexed by the resource name, which
17 2cb83537 Giorgos Korfiatis
contains a number of attributes for each resource.
18 b32b5995 Giorgos Korfiatis
19 2cb83537 Giorgos Korfiatis
**Response Codes**:
20 b32b5995 Giorgos Korfiatis
21 b32b5995 Giorgos Korfiatis
======  =====================
22 b32b5995 Giorgos Korfiatis
Status  Description
23 b32b5995 Giorgos Korfiatis
======  =====================
24 2cb83537 Giorgos Korfiatis
200     Success
25 b32b5995 Giorgos Korfiatis
500     Internal Server Error
26 b32b5995 Giorgos Korfiatis
======  =====================
27 b32b5995 Giorgos Korfiatis
28 b32b5995 Giorgos Korfiatis
**Example Successful Response**:
29 b32b5995 Giorgos Korfiatis
30 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
31 b32b5995 Giorgos Korfiatis
32 b32b5995 Giorgos Korfiatis
  {
33 b32b5995 Giorgos Korfiatis
      "cyclades.vm": {
34 b32b5995 Giorgos Korfiatis
          "unit": null,
35 b32b5995 Giorgos Korfiatis
          "description": "Number of virtual machines",
36 0e08e08e Giorgos Korfiatis
          "service": "cyclades_compute",
37 c8618788 Giorgos Korfiatis
          "allow_in_projects": true
38 b32b5995 Giorgos Korfiatis
          },
39 b32b5995 Giorgos Korfiatis
      "cyclades.ram": {
40 b32b5995 Giorgos Korfiatis
          "unit": "bytes",
41 b32b5995 Giorgos Korfiatis
          "description": "Virtual machine memory",
42 0e08e08e Giorgos Korfiatis
          "service": "cyclades_compute",
43 c8618788 Giorgos Korfiatis
          "allow_in_projects": true
44 b32b5995 Giorgos Korfiatis
          }
45 b32b5995 Giorgos Korfiatis
  }
46 b32b5995 Giorgos Korfiatis
47 b32b5995 Giorgos Korfiatis
Quotas
48 b32b5995 Giorgos Korfiatis
------
49 b32b5995 Giorgos Korfiatis
50 2cb83537 Giorgos Korfiatis
The system specifies user quotas for each available resource. Resources
51 2cb83537 Giorgos Korfiatis
can be allocated from various sources. By default, users get resources
52 2cb83537 Giorgos Korfiatis
from a single source, called ``system``. For each combination of user,
53 2cb83537 Giorgos Korfiatis
source, and resource, the quota system keeps track of the maximum allowed
54 2cb83537 Giorgos Korfiatis
value (limit) and the current actual usage. The former is controlled by
55 2cb83537 Giorgos Korfiatis
the policy defined in Astakos; the latter is updated by the services that
56 2cb83537 Giorgos Korfiatis
actually implement the resource each time an allocation or deallocation
57 2cb83537 Giorgos Korfiatis
takes place.
58 2cb83537 Giorgos Korfiatis
59 b32b5995 Giorgos Korfiatis
Get Quotas
60 b32b5995 Giorgos Korfiatis
..........
61 b32b5995 Giorgos Korfiatis
62 7421af4a Giorgos Korfiatis
**GET** /account/v1.0/quotas
63 b32b5995 Giorgos Korfiatis
64 b32b5995 Giorgos Korfiatis
====================  =========================
65 b32b5995 Giorgos Korfiatis
Request Header Name   Value
66 b32b5995 Giorgos Korfiatis
====================  =========================
67 b32b5995 Giorgos Korfiatis
X-Auth-Token          User authentication token
68 b32b5995 Giorgos Korfiatis
====================  =========================
69 b32b5995 Giorgos Korfiatis
70 2cb83537 Giorgos Korfiatis
A user can query their resources with this call. It returns in a nested
71 2cb83537 Giorgos Korfiatis
dictionary structure, for each source and resource, three indicators.
72 2cb83537 Giorgos Korfiatis
``limit`` and ``usage`` are as explained above. ``pending`` is related to the
73 2cb83537 Giorgos Korfiatis
commissioning system explained below. Roughly, if ``pending`` is non zero,
74 2cb83537 Giorgos Korfiatis
this indicates that some resource allocation process has started but not
75 2cb83537 Giorgos Korfiatis
finished properly.
76 b32b5995 Giorgos Korfiatis
77 2cb83537 Giorgos Korfiatis
**Response Codes**:
78 b32b5995 Giorgos Korfiatis
79 b32b5995 Giorgos Korfiatis
======  ============================
80 b32b5995 Giorgos Korfiatis
Status  Description
81 b32b5995 Giorgos Korfiatis
======  ============================
82 2cb83537 Giorgos Korfiatis
200     Success
83 b32b5995 Giorgos Korfiatis
401     Unauthorized (Missing token)
84 b32b5995 Giorgos Korfiatis
500     Internal Server Error
85 b32b5995 Giorgos Korfiatis
======  ============================
86 b32b5995 Giorgos Korfiatis
87 b32b5995 Giorgos Korfiatis
**Example Successful Response**:
88 b32b5995 Giorgos Korfiatis
89 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
90 b32b5995 Giorgos Korfiatis
91 b32b5995 Giorgos Korfiatis
  {
92 b32b5995 Giorgos Korfiatis
      "system": {
93 b32b5995 Giorgos Korfiatis
          "cyclades.ram": {
94 480974e6 Giorgos Korfiatis
              "usage": 536870912,
95 b32b5995 Giorgos Korfiatis
              "limit": 1073741824,
96 480974e6 Giorgos Korfiatis
              "pending": 0
97 480974e6 Giorgos Korfiatis
98 b32b5995 Giorgos Korfiatis
          },
99 b32b5995 Giorgos Korfiatis
          "cyclades.vm": {
100 480974e6 Giorgos Korfiatis
              "usage": 2,
101 b32b5995 Giorgos Korfiatis
              "limit": 2,
102 480974e6 Giorgos Korfiatis
              "pending": 0
103 b32b5995 Giorgos Korfiatis
          }
104 b32b5995 Giorgos Korfiatis
      },
105 b32b5995 Giorgos Korfiatis
      "project:1": {
106 b32b5995 Giorgos Korfiatis
          "cyclades.ram": {
107 480974e6 Giorgos Korfiatis
              "usage": 2147483648,
108 b32b5995 Giorgos Korfiatis
              "limit": 2147483648,
109 480974e6 Giorgos Korfiatis
              "pending": 0
110 b32b5995 Giorgos Korfiatis
          },
111 b32b5995 Giorgos Korfiatis
          "cyclades.vm": {
112 480974e6 Giorgos Korfiatis
              "usage": 2,
113 b32b5995 Giorgos Korfiatis
              "limit": 5,
114 480974e6 Giorgos Korfiatis
              "pending": 1
115 b32b5995 Giorgos Korfiatis
          }
116 b32b5995 Giorgos Korfiatis
      }
117 b32b5995 Giorgos Korfiatis
  }
118 b32b5995 Giorgos Korfiatis
119 bb005bc2 Giorgos Korfiatis
Get Quotas per Service
120 5afce44d Giorgos Korfiatis
......................
121 bb005bc2 Giorgos Korfiatis
122 7421af4a Giorgos Korfiatis
**GET** /account/v1.0/service_quotas
123 bb005bc2 Giorgos Korfiatis
124 bb005bc2 Giorgos Korfiatis
====================  ============================
125 bb005bc2 Giorgos Korfiatis
Request Header Name   Value
126 bb005bc2 Giorgos Korfiatis
====================  ============================
127 bb005bc2 Giorgos Korfiatis
X-Auth-Token          Service authentication token
128 bb005bc2 Giorgos Korfiatis
====================  ============================
129 bb005bc2 Giorgos Korfiatis
130 2cb83537 Giorgos Korfiatis
A service can query the quotas for all resources related to it. By default,
131 2cb83537 Giorgos Korfiatis
it returns the quotas for all users, in the format explained above, indexed
132 2cb83537 Giorgos Korfiatis
by the user identifier (UUID).
133 2cb83537 Giorgos Korfiatis
134 2cb83537 Giorgos Korfiatis
Use the GET parameter ``?user=<uuid>`` to query for a single user.
135 5afce44d Giorgos Korfiatis
136 bb005bc2 Giorgos Korfiatis
137 2cb83537 Giorgos Korfiatis
**Response Codes**:
138 bb005bc2 Giorgos Korfiatis
139 bb005bc2 Giorgos Korfiatis
======  ============================
140 bb005bc2 Giorgos Korfiatis
Status  Description
141 bb005bc2 Giorgos Korfiatis
======  ============================
142 2cb83537 Giorgos Korfiatis
200     Success
143 bb005bc2 Giorgos Korfiatis
401     Unauthorized (Missing token)
144 bb005bc2 Giorgos Korfiatis
500     Internal Server Error
145 bb005bc2 Giorgos Korfiatis
======  ============================
146 bb005bc2 Giorgos Korfiatis
147 bb005bc2 Giorgos Korfiatis
**Example Successful Response**:
148 bb005bc2 Giorgos Korfiatis
149 bb005bc2 Giorgos Korfiatis
.. code-block:: javascript
150 bb005bc2 Giorgos Korfiatis
151 bb005bc2 Giorgos Korfiatis
  {
152 bb005bc2 Giorgos Korfiatis
      "1a6165d0-5020-4b6d-a4ad-83476632a584": {
153 bb005bc2 Giorgos Korfiatis
          "system": {
154 bb005bc2 Giorgos Korfiatis
              "cyclades.ram": {
155 480974e6 Giorgos Korfiatis
                  "usage": 536870912,
156 bb005bc2 Giorgos Korfiatis
                  "limit": 1073741824,
157 480974e6 Giorgos Korfiatis
                  "pending": 0
158 bb005bc2 Giorgos Korfiatis
              },
159 bb005bc2 Giorgos Korfiatis
              "cyclades.vm": {
160 480974e6 Giorgos Korfiatis
                  "usage": 2,
161 bb005bc2 Giorgos Korfiatis
                  "limit": 2,
162 480974e6 Giorgos Korfiatis
                  "pending": 0
163 bb005bc2 Giorgos Korfiatis
              }
164 bb005bc2 Giorgos Korfiatis
          },
165 bb005bc2 Giorgos Korfiatis
          "project:1": {
166 bb005bc2 Giorgos Korfiatis
              "cyclades.ram": {
167 480974e6 Giorgos Korfiatis
                  "usage": 2147483648,
168 bb005bc2 Giorgos Korfiatis
                  "limit": 2147483648,
169 480974e6 Giorgos Korfiatis
                  "pending": 0
170 bb005bc2 Giorgos Korfiatis
              },
171 bb005bc2 Giorgos Korfiatis
              "cyclades.vm": {
172 480974e6 Giorgos Korfiatis
                  "usage": 2,
173 bb005bc2 Giorgos Korfiatis
                  "limit": 5,
174 480974e6 Giorgos Korfiatis
                  "pending": 1
175 bb005bc2 Giorgos Korfiatis
              }
176 bb005bc2 Giorgos Korfiatis
          }
177 bb005bc2 Giorgos Korfiatis
      }
178 bb005bc2 Giorgos Korfiatis
  }
179 bb005bc2 Giorgos Korfiatis
180 b32b5995 Giorgos Korfiatis
Commissions
181 b32b5995 Giorgos Korfiatis
-----------
182 b32b5995 Giorgos Korfiatis
183 2cb83537 Giorgos Korfiatis
When a resource allocation is about to take place, the service that performs
184 2cb83537 Giorgos Korfiatis
this operation can query the quota system to find out whether the planned
185 2cb83537 Giorgos Korfiatis
allocation would surpass some defined limits. If this is not the case, the
186 2cb83537 Giorgos Korfiatis
quota system registers this pending allocation. Upon the actual allocation
187 2cb83537 Giorgos Korfiatis
of resources, the service informs the quota system to definitely update the
188 2cb83537 Giorgos Korfiatis
usage.
189 2cb83537 Giorgos Korfiatis
190 2cb83537 Giorgos Korfiatis
Thus, changing quotas consists of two steps: in the first, the service
191 2cb83537 Giorgos Korfiatis
issues a *commission*, indicating which extra resources will be given to
192 2cb83537 Giorgos Korfiatis
particular users; in the second, it finalizes the commission by *accepting*
193 2cb83537 Giorgos Korfiatis
it (or *rejecting*, if the allocation did not actually take place).
194 2cb83537 Giorgos Korfiatis
195 b32b5995 Giorgos Korfiatis
Issue Commission
196 b32b5995 Giorgos Korfiatis
................
197 b32b5995 Giorgos Korfiatis
198 7421af4a Giorgos Korfiatis
**POST** /account/v1.0/commissions
199 b32b5995 Giorgos Korfiatis
200 b32b5995 Giorgos Korfiatis
====================  ============================
201 b32b5995 Giorgos Korfiatis
Request Header Name   Value
202 b32b5995 Giorgos Korfiatis
====================  ============================
203 b32b5995 Giorgos Korfiatis
X-Auth-Token          Service authentication token
204 b32b5995 Giorgos Korfiatis
====================  ============================
205 b32b5995 Giorgos Korfiatis
206 2cb83537 Giorgos Korfiatis
A service issues a commission by providing a list of *provisions*, i.e.
207 2cb83537 Giorgos Korfiatis
the intended allocation for a particular user (in general, ``holder``),
208 2cb83537 Giorgos Korfiatis
``source``, and ``resource`` combination.
209 b32b5995 Giorgos Korfiatis
210 2cb83537 Giorgos Korfiatis
The request body consists of a JSON dict (as in the example below), which
211 2cb83537 Giorgos Korfiatis
apart from the provisions list can also contain the following optional
212 2cb83537 Giorgos Korfiatis
fields:
213 b32b5995 Giorgos Korfiatis
214 2cb83537 Giorgos Korfiatis
 * ``name``: An optional description of the operation
215 2cb83537 Giorgos Korfiatis
 * ``force``: Succeed even if a limit is surpassed
216 2cb83537 Giorgos Korfiatis
 * ``auto_accept``: Perform the two steps at once
217 b32b5995 Giorgos Korfiatis
218 b32b5995 Giorgos Korfiatis
**Example Request**:
219 b32b5995 Giorgos Korfiatis
220 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
221 b32b5995 Giorgos Korfiatis
222 b32b5995 Giorgos Korfiatis
  {
223 b32b5995 Giorgos Korfiatis
      "force": false,
224 b32b5995 Giorgos Korfiatis
      "auto_accept": false,
225 3a1bed03 Giorgos Korfiatis
      "name": "an optional description",
226 b32b5995 Giorgos Korfiatis
      "provisions": [
227 b32b5995 Giorgos Korfiatis
          {
228 b32b5995 Giorgos Korfiatis
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
229 b32b5995 Giorgos Korfiatis
              "source": "system",
230 b32b5995 Giorgos Korfiatis
              "resource": "cyclades.vm",
231 b32b5995 Giorgos Korfiatis
              "quantity": 1
232 b32b5995 Giorgos Korfiatis
          },
233 b32b5995 Giorgos Korfiatis
          {
234 b32b5995 Giorgos Korfiatis
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
235 b32b5995 Giorgos Korfiatis
              "source": "system",
236 b32b5995 Giorgos Korfiatis
              "resource": "cyclades.ram",
237 b32b5995 Giorgos Korfiatis
              "quantity": 536870912
238 b32b5995 Giorgos Korfiatis
          }
239 b32b5995 Giorgos Korfiatis
      ]
240 b32b5995 Giorgos Korfiatis
  }
241 b32b5995 Giorgos Korfiatis
242 2cb83537 Giorgos Korfiatis
**Response Codes**:
243 2cb83537 Giorgos Korfiatis
244 2cb83537 Giorgos Korfiatis
======  =======================================================
245 2cb83537 Giorgos Korfiatis
Status  Description
246 2cb83537 Giorgos Korfiatis
======  =======================================================
247 2cb83537 Giorgos Korfiatis
201     Success
248 2cb83537 Giorgos Korfiatis
400     Commission failed due to invalid input data
249 2cb83537 Giorgos Korfiatis
401     Unauthorized (Missing token)
250 2cb83537 Giorgos Korfiatis
404     Cannot find one of the target holdings
251 2cb83537 Giorgos Korfiatis
413     A quantity fell below zero in one of the holdings
252 2cb83537 Giorgos Korfiatis
413     A quantity exceeded the capacity in one of the holdings
253 2cb83537 Giorgos Korfiatis
500     Internal Server Error
254 2cb83537 Giorgos Korfiatis
======  =======================================================
255 2cb83537 Giorgos Korfiatis
256 2cb83537 Giorgos Korfiatis
On a successful commission, the call responds with a ``serial``, an identifier
257 2cb83537 Giorgos Korfiatis
for the commission. On failure, in the case of ``overLimit`` (413) or
258 2cb83537 Giorgos Korfiatis
``itemNotFound`` (404), the returned cloudFault contains an extra field
259 2cb83537 Giorgos Korfiatis
``data`` with additional application-specific information. It contains at
260 2cb83537 Giorgos Korfiatis
least the ``provision`` that is to blame and the actual ``name`` of the
261 3a8e56bc Giorgos Korfiatis
exception raised. In the case of ``overLimit``, ``limit`` and ``usage`` are
262 3a8e56bc Giorgos Korfiatis
also included.
263 2cb83537 Giorgos Korfiatis
264 b32b5995 Giorgos Korfiatis
**Example Successful Response**:
265 b32b5995 Giorgos Korfiatis
266 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
267 b32b5995 Giorgos Korfiatis
268 b32b5995 Giorgos Korfiatis
  {
269 b32b5995 Giorgos Korfiatis
      "serial": 57
270 b32b5995 Giorgos Korfiatis
  }
271 b32b5995 Giorgos Korfiatis
272 b32b5995 Giorgos Korfiatis
**Example Failure Response**:
273 b32b5995 Giorgos Korfiatis
274 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
275 b32b5995 Giorgos Korfiatis
276 b32b5995 Giorgos Korfiatis
  {
277 b32b5995 Giorgos Korfiatis
      "overLimit": {
278 b32b5995 Giorgos Korfiatis
          "message": "a human-readable error message",
279 b32b5995 Giorgos Korfiatis
          "code": 413,
280 b32b5995 Giorgos Korfiatis
          "data": {
281 b32b5995 Giorgos Korfiatis
              "provision": {
282 b32b5995 Giorgos Korfiatis
                  "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
283 b32b5995 Giorgos Korfiatis
                  "source": "system",
284 b32b5995 Giorgos Korfiatis
                  "resource": "cyclades.vm",
285 b32b5995 Giorgos Korfiatis
                  "quantity": 1
286 b32b5995 Giorgos Korfiatis
              },
287 b32b5995 Giorgos Korfiatis
              "name": "NoCapacityError",
288 e311d555 Giorgos Korfiatis
              "limit": 2,
289 e311d555 Giorgos Korfiatis
              "usage": 2
290 b32b5995 Giorgos Korfiatis
          }
291 b32b5995 Giorgos Korfiatis
      }
292 b32b5995 Giorgos Korfiatis
  }
293 b32b5995 Giorgos Korfiatis
294 b32b5995 Giorgos Korfiatis
Get Pending Commissions
295 b32b5995 Giorgos Korfiatis
.......................
296 b32b5995 Giorgos Korfiatis
297 7421af4a Giorgos Korfiatis
**GET** /account/v1.0/commissions
298 b32b5995 Giorgos Korfiatis
299 b32b5995 Giorgos Korfiatis
====================  ============================
300 b32b5995 Giorgos Korfiatis
Request Header Name   Value
301 b32b5995 Giorgos Korfiatis
====================  ============================
302 b32b5995 Giorgos Korfiatis
X-Auth-Token          Service authentication token
303 b32b5995 Giorgos Korfiatis
====================  ============================
304 b32b5995 Giorgos Korfiatis
305 2cb83537 Giorgos Korfiatis
The service can query the quota system for all *pending* commissions
306 2cb83537 Giorgos Korfiatis
initiated by itself, that is, all commissions that have been issued
307 2cb83537 Giorgos Korfiatis
but not accepted or rejected (see below). The call responds with the list
308 2cb83537 Giorgos Korfiatis
of the serials of all pending commissions.
309 b32b5995 Giorgos Korfiatis
310 2cb83537 Giorgos Korfiatis
**Response Codes**:
311 b32b5995 Giorgos Korfiatis
312 b32b5995 Giorgos Korfiatis
======  ============================
313 b32b5995 Giorgos Korfiatis
Status  Description
314 b32b5995 Giorgos Korfiatis
======  ============================
315 2cb83537 Giorgos Korfiatis
200     Success
316 b32b5995 Giorgos Korfiatis
401     Unauthorized (Missing token)
317 b32b5995 Giorgos Korfiatis
500     Internal Server Error
318 b32b5995 Giorgos Korfiatis
======  ============================
319 b32b5995 Giorgos Korfiatis
320 b32b5995 Giorgos Korfiatis
**Example Successful Response**:
321 b32b5995 Giorgos Korfiatis
322 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
323 b32b5995 Giorgos Korfiatis
324 b32b5995 Giorgos Korfiatis
  [<serial>, ...]
325 b32b5995 Giorgos Korfiatis
326 b32b5995 Giorgos Korfiatis
Get the Description of a Commission
327 b32b5995 Giorgos Korfiatis
...................................
328 b32b5995 Giorgos Korfiatis
329 7421af4a Giorgos Korfiatis
**GET** /account/v1.0/commissions/<serial>
330 b32b5995 Giorgos Korfiatis
331 b32b5995 Giorgos Korfiatis
====================  ============================
332 b32b5995 Giorgos Korfiatis
Request Header Name   Value
333 b32b5995 Giorgos Korfiatis
====================  ============================
334 b32b5995 Giorgos Korfiatis
X-Auth-Token          Service authentication token
335 b32b5995 Giorgos Korfiatis
====================  ============================
336 b32b5995 Giorgos Korfiatis
337 2cb83537 Giorgos Korfiatis
This call allows a service to retrieve information for a pending commission.
338 b32b5995 Giorgos Korfiatis
339 2cb83537 Giorgos Korfiatis
**Response Codes**:
340 b32b5995 Giorgos Korfiatis
341 b32b5995 Giorgos Korfiatis
======  ============================
342 b32b5995 Giorgos Korfiatis
Status  Description
343 b32b5995 Giorgos Korfiatis
======  ============================
344 2cb83537 Giorgos Korfiatis
200     Success
345 b32b5995 Giorgos Korfiatis
401     Unauthorized (Missing token)
346 b32b5995 Giorgos Korfiatis
404     Commission Not Found
347 b32b5995 Giorgos Korfiatis
500     Internal Server Error
348 b32b5995 Giorgos Korfiatis
======  ============================
349 b32b5995 Giorgos Korfiatis
350 b32b5995 Giorgos Korfiatis
**Example Successful Response**:
351 b32b5995 Giorgos Korfiatis
352 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
353 b32b5995 Giorgos Korfiatis
354 b32b5995 Giorgos Korfiatis
  {
355 b32b5995 Giorgos Korfiatis
      "serial": 57,
356 164e64d5 Giorgos Korfiatis
      "issue_time": "2013-04-08T10:19:15.0373+00:00",
357 3a1bed03 Giorgos Korfiatis
      "name": "an optional description",
358 b32b5995 Giorgos Korfiatis
      "provisions": [
359 b32b5995 Giorgos Korfiatis
          {
360 b32b5995 Giorgos Korfiatis
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
361 b32b5995 Giorgos Korfiatis
              "source": "system",
362 b32b5995 Giorgos Korfiatis
              "resource": "cyclades.vm",
363 b32b5995 Giorgos Korfiatis
              "quantity": 1
364 b32b5995 Giorgos Korfiatis
          },
365 b32b5995 Giorgos Korfiatis
          {
366 b32b5995 Giorgos Korfiatis
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
367 b32b5995 Giorgos Korfiatis
              "source": "system",
368 b32b5995 Giorgos Korfiatis
              "resource": "cyclades.ram",
369 b32b5995 Giorgos Korfiatis
              "quantity": 536870912
370 b32b5995 Giorgos Korfiatis
          }
371 b32b5995 Giorgos Korfiatis
      ]
372 b32b5995 Giorgos Korfiatis
  }
373 b32b5995 Giorgos Korfiatis
374 b32b5995 Giorgos Korfiatis
Accept or Reject a Commission
375 b32b5995 Giorgos Korfiatis
.............................
376 b32b5995 Giorgos Korfiatis
377 7421af4a Giorgos Korfiatis
**POST** /account/v1.0/commissions/<serial>/action
378 b32b5995 Giorgos Korfiatis
379 b32b5995 Giorgos Korfiatis
====================  ============================
380 b32b5995 Giorgos Korfiatis
Request Header Name   Value
381 b32b5995 Giorgos Korfiatis
====================  ============================
382 b32b5995 Giorgos Korfiatis
X-Auth-Token          Service authentication token
383 b32b5995 Giorgos Korfiatis
====================  ============================
384 b32b5995 Giorgos Korfiatis
385 2cb83537 Giorgos Korfiatis
With this call a service can *accept* or *reject* a pending commission, that
386 2cb83537 Giorgos Korfiatis
is, finalize the registered usage or undo commission issued.
387 2cb83537 Giorgos Korfiatis
The system guarantees that a commission can always be later accepted
388 2cb83537 Giorgos Korfiatis
or rejected, no matter what other commissions have taken place in the meantime.
389 b32b5995 Giorgos Korfiatis
390 2cb83537 Giorgos Korfiatis
To accept, include in the request body a field indexed by ``accept``;
391 2cb83537 Giorgos Korfiatis
likewise for rejecting.
392 b32b5995 Giorgos Korfiatis
393 b32b5995 Giorgos Korfiatis
**Example Requests**:
394 b32b5995 Giorgos Korfiatis
395 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
396 b32b5995 Giorgos Korfiatis
397 b32b5995 Giorgos Korfiatis
  {
398 b32b5995 Giorgos Korfiatis
      "accept": ""
399 b32b5995 Giorgos Korfiatis
  }
400 b32b5995 Giorgos Korfiatis
401 b32b5995 Giorgos Korfiatis
  {
402 b32b5995 Giorgos Korfiatis
      "reject": ""
403 b32b5995 Giorgos Korfiatis
  }
404 b32b5995 Giorgos Korfiatis
405 2cb83537 Giorgos Korfiatis
**Response Codes**:
406 2cb83537 Giorgos Korfiatis
407 2cb83537 Giorgos Korfiatis
======  ============================
408 2cb83537 Giorgos Korfiatis
Status  Description
409 2cb83537 Giorgos Korfiatis
======  ============================
410 2cb83537 Giorgos Korfiatis
200     Success
411 2cb83537 Giorgos Korfiatis
401     Unauthorized (Missing token)
412 2cb83537 Giorgos Korfiatis
404     Commission Not Found
413 2cb83537 Giorgos Korfiatis
500     Internal Server Error
414 2cb83537 Giorgos Korfiatis
======  ============================
415 2cb83537 Giorgos Korfiatis
416 b32b5995 Giorgos Korfiatis
Accept or Reject Multiple Commissions
417 b32b5995 Giorgos Korfiatis
.....................................
418 b32b5995 Giorgos Korfiatis
419 7421af4a Giorgos Korfiatis
**POST** /account/v1.0/commissions/action
420 b32b5995 Giorgos Korfiatis
421 b32b5995 Giorgos Korfiatis
====================  ============================
422 b32b5995 Giorgos Korfiatis
Request Header Name   Value
423 b32b5995 Giorgos Korfiatis
====================  ============================
424 b32b5995 Giorgos Korfiatis
X-Auth-Token          Service authentication token
425 b32b5995 Giorgos Korfiatis
====================  ============================
426 b32b5995 Giorgos Korfiatis
427 2cb83537 Giorgos Korfiatis
This allows to accept and reject multiple commissions in the same time,
428 2cb83537 Giorgos Korfiatis
by including the list of serials to accept and the list of serials to reject
429 2cb83537 Giorgos Korfiatis
in the request body.
430 b32b5995 Giorgos Korfiatis
431 b32b5995 Giorgos Korfiatis
**Example Request**:
432 b32b5995 Giorgos Korfiatis
433 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
434 b32b5995 Giorgos Korfiatis
435 b32b5995 Giorgos Korfiatis
  {
436 b32b5995 Giorgos Korfiatis
      "accept": [56, 57],
437 b32b5995 Giorgos Korfiatis
      "reject": [56, 58, 59]
438 b32b5995 Giorgos Korfiatis
  }
439 b32b5995 Giorgos Korfiatis
440 2cb83537 Giorgos Korfiatis
The response includes the list of serials that have been actually
441 2cb83537 Giorgos Korfiatis
``accepted`` or ``rejected`` and those that ``failed``. The latter
442 2cb83537 Giorgos Korfiatis
consists of a list of pairs. The first element of the pair is a serial
443 2cb83537 Giorgos Korfiatis
that failed, the second element is a cloudFault describing the failure.
444 2cb83537 Giorgos Korfiatis
445 2cb83537 Giorgos Korfiatis
**Response Codes**:
446 2cb83537 Giorgos Korfiatis
447 2cb83537 Giorgos Korfiatis
======  ============================
448 2cb83537 Giorgos Korfiatis
Status  Description
449 2cb83537 Giorgos Korfiatis
======  ============================
450 2cb83537 Giorgos Korfiatis
200     Success
451 2cb83537 Giorgos Korfiatis
401     Unauthorized (Missing token)
452 2cb83537 Giorgos Korfiatis
500     Internal Server Error
453 2cb83537 Giorgos Korfiatis
======  ============================
454 2cb83537 Giorgos Korfiatis
455 b32b5995 Giorgos Korfiatis
**Example Successful Response**:
456 b32b5995 Giorgos Korfiatis
457 b32b5995 Giorgos Korfiatis
.. code-block:: javascript
458 b32b5995 Giorgos Korfiatis
459 b32b5995 Giorgos Korfiatis
  { "accepted": [57],
460 b32b5995 Giorgos Korfiatis
    "rejected": [59],
461 b32b5995 Giorgos Korfiatis
    "failed": [
462 b32b5995 Giorgos Korfiatis
        [56, {
463 b32b5995 Giorgos Korfiatis
                 "badRequest": {
464 b32b5995 Giorgos Korfiatis
                     "message": "cannot both accept and reject serial 56",
465 b32b5995 Giorgos Korfiatis
                     "code": 400
466 b32b5995 Giorgos Korfiatis
                     }
467 b32b5995 Giorgos Korfiatis
                 }
468 b32b5995 Giorgos Korfiatis
        ],
469 b32b5995 Giorgos Korfiatis
        [58, {
470 b32b5995 Giorgos Korfiatis
                 "itemNotFound": {
471 b32b5995 Giorgos Korfiatis
                     "message": "serial 58 does not exist",
472 b32b5995 Giorgos Korfiatis
                     "code": 404
473 b32b5995 Giorgos Korfiatis
                     }
474 b32b5995 Giorgos Korfiatis
                 }
475 b32b5995 Giorgos Korfiatis
        ]
476 b32b5995 Giorgos Korfiatis
    ]
477 b32b5995 Giorgos Korfiatis
  }