root / docs / quota-api-guide.rst @ c8618788
History | View | Annotate | Download (13.3 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 | b32b5995 | Giorgos Korfiatis | **GET** /astakos/api/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 | c8618788 | Giorgos Korfiatis | "service": "cyclades", |
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 | c8618788 | Giorgos Korfiatis | "service": "cyclades", |
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 | b32b5995 | Giorgos Korfiatis | **GET** /astakos/api/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 | bb005bc2 | Giorgos Korfiatis | **GET** /astakos/api/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 | b32b5995 | Giorgos Korfiatis | **POST** /astakos/api/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 | 2cb83537 | Giorgos Korfiatis | exception raised. In case of ``NoCapacityError``, ``limit`` and ``usage`` are |
262 | 2cb83537 | Giorgos Korfiatis | also included; in case of ``NoQuantityError`` (that is, when attempting to |
263 | 2cb83537 | Giorgos Korfiatis | release a value greater than what is registered), the ``available`` quantity |
264 | 2cb83537 | Giorgos Korfiatis | is provided. |
265 | 2cb83537 | Giorgos Korfiatis | |
266 | b32b5995 | Giorgos Korfiatis | **Example Successful Response**: |
267 | b32b5995 | Giorgos Korfiatis | |
268 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
269 | b32b5995 | Giorgos Korfiatis | |
270 | b32b5995 | Giorgos Korfiatis | { |
271 | b32b5995 | Giorgos Korfiatis | "serial": 57 |
272 | b32b5995 | Giorgos Korfiatis | } |
273 | b32b5995 | Giorgos Korfiatis | |
274 | b32b5995 | Giorgos Korfiatis | **Example Failure Response**: |
275 | b32b5995 | Giorgos Korfiatis | |
276 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
277 | b32b5995 | Giorgos Korfiatis | |
278 | b32b5995 | Giorgos Korfiatis | { |
279 | b32b5995 | Giorgos Korfiatis | "overLimit": { |
280 | b32b5995 | Giorgos Korfiatis | "message": "a human-readable error message", |
281 | b32b5995 | Giorgos Korfiatis | "code": 413, |
282 | b32b5995 | Giorgos Korfiatis | "data": { |
283 | b32b5995 | Giorgos Korfiatis | "provision": { |
284 | b32b5995 | Giorgos Korfiatis | "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
285 | b32b5995 | Giorgos Korfiatis | "source": "system", |
286 | b32b5995 | Giorgos Korfiatis | "resource": "cyclades.vm", |
287 | b32b5995 | Giorgos Korfiatis | "quantity": 1 |
288 | b32b5995 | Giorgos Korfiatis | }, |
289 | b32b5995 | Giorgos Korfiatis | "name": "NoCapacityError", |
290 | e311d555 | Giorgos Korfiatis | "limit": 2, |
291 | e311d555 | Giorgos Korfiatis | "usage": 2 |
292 | b32b5995 | Giorgos Korfiatis | } |
293 | b32b5995 | Giorgos Korfiatis | } |
294 | b32b5995 | Giorgos Korfiatis | } |
295 | b32b5995 | Giorgos Korfiatis | |
296 | b32b5995 | Giorgos Korfiatis | Get Pending Commissions |
297 | b32b5995 | Giorgos Korfiatis | ....................... |
298 | b32b5995 | Giorgos Korfiatis | |
299 | b32b5995 | Giorgos Korfiatis | **GET** /astakos/api/commissions |
300 | b32b5995 | Giorgos Korfiatis | |
301 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
302 | b32b5995 | Giorgos Korfiatis | Request Header Name Value |
303 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
304 | b32b5995 | Giorgos Korfiatis | X-Auth-Token Service authentication token |
305 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
306 | b32b5995 | Giorgos Korfiatis | |
307 | 2cb83537 | Giorgos Korfiatis | The service can query the quota system for all *pending* commissions |
308 | 2cb83537 | Giorgos Korfiatis | initiated by itself, that is, all commissions that have been issued |
309 | 2cb83537 | Giorgos Korfiatis | but not accepted or rejected (see below). The call responds with the list |
310 | 2cb83537 | Giorgos Korfiatis | of the serials of all pending commissions. |
311 | b32b5995 | Giorgos Korfiatis | |
312 | 2cb83537 | Giorgos Korfiatis | **Response Codes**: |
313 | b32b5995 | Giorgos Korfiatis | |
314 | b32b5995 | Giorgos Korfiatis | ====== ============================ |
315 | b32b5995 | Giorgos Korfiatis | Status Description |
316 | b32b5995 | Giorgos Korfiatis | ====== ============================ |
317 | 2cb83537 | Giorgos Korfiatis | 200 Success |
318 | b32b5995 | Giorgos Korfiatis | 401 Unauthorized (Missing token) |
319 | b32b5995 | Giorgos Korfiatis | 500 Internal Server Error |
320 | b32b5995 | Giorgos Korfiatis | ====== ============================ |
321 | b32b5995 | Giorgos Korfiatis | |
322 | b32b5995 | Giorgos Korfiatis | **Example Successful Response**: |
323 | b32b5995 | Giorgos Korfiatis | |
324 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
325 | b32b5995 | Giorgos Korfiatis | |
326 | b32b5995 | Giorgos Korfiatis | [<serial>, ...] |
327 | b32b5995 | Giorgos Korfiatis | |
328 | b32b5995 | Giorgos Korfiatis | Get the Description of a Commission |
329 | b32b5995 | Giorgos Korfiatis | ................................... |
330 | b32b5995 | Giorgos Korfiatis | |
331 | b32b5995 | Giorgos Korfiatis | **GET** /astakos/api/commissions/<serial> |
332 | b32b5995 | Giorgos Korfiatis | |
333 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
334 | b32b5995 | Giorgos Korfiatis | Request Header Name Value |
335 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
336 | b32b5995 | Giorgos Korfiatis | X-Auth-Token Service authentication token |
337 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
338 | b32b5995 | Giorgos Korfiatis | |
339 | 2cb83537 | Giorgos Korfiatis | This call allows a service to retrieve information for a pending commission. |
340 | b32b5995 | Giorgos Korfiatis | |
341 | 2cb83537 | Giorgos Korfiatis | **Response Codes**: |
342 | b32b5995 | Giorgos Korfiatis | |
343 | b32b5995 | Giorgos Korfiatis | ====== ============================ |
344 | b32b5995 | Giorgos Korfiatis | Status Description |
345 | b32b5995 | Giorgos Korfiatis | ====== ============================ |
346 | 2cb83537 | Giorgos Korfiatis | 200 Success |
347 | b32b5995 | Giorgos Korfiatis | 401 Unauthorized (Missing token) |
348 | b32b5995 | Giorgos Korfiatis | 404 Commission Not Found |
349 | b32b5995 | Giorgos Korfiatis | 500 Internal Server Error |
350 | b32b5995 | Giorgos Korfiatis | ====== ============================ |
351 | b32b5995 | Giorgos Korfiatis | |
352 | b32b5995 | Giorgos Korfiatis | **Example Successful Response**: |
353 | b32b5995 | Giorgos Korfiatis | |
354 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
355 | b32b5995 | Giorgos Korfiatis | |
356 | b32b5995 | Giorgos Korfiatis | { |
357 | b32b5995 | Giorgos Korfiatis | "serial": 57, |
358 | b32b5995 | Giorgos Korfiatis | "issue_time": "2013-04-08T10:19:15.0373", |
359 | 3a1bed03 | Giorgos Korfiatis | "name": "an optional description", |
360 | b32b5995 | Giorgos Korfiatis | "provisions": [ |
361 | b32b5995 | Giorgos Korfiatis | { |
362 | b32b5995 | Giorgos Korfiatis | "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
363 | b32b5995 | Giorgos Korfiatis | "source": "system", |
364 | b32b5995 | Giorgos Korfiatis | "resource": "cyclades.vm", |
365 | b32b5995 | Giorgos Korfiatis | "quantity": 1 |
366 | b32b5995 | Giorgos Korfiatis | }, |
367 | b32b5995 | Giorgos Korfiatis | { |
368 | b32b5995 | Giorgos Korfiatis | "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
369 | b32b5995 | Giorgos Korfiatis | "source": "system", |
370 | b32b5995 | Giorgos Korfiatis | "resource": "cyclades.ram", |
371 | b32b5995 | Giorgos Korfiatis | "quantity": 536870912 |
372 | b32b5995 | Giorgos Korfiatis | } |
373 | b32b5995 | Giorgos Korfiatis | ] |
374 | b32b5995 | Giorgos Korfiatis | } |
375 | b32b5995 | Giorgos Korfiatis | |
376 | b32b5995 | Giorgos Korfiatis | Accept or Reject a Commission |
377 | b32b5995 | Giorgos Korfiatis | ............................. |
378 | b32b5995 | Giorgos Korfiatis | |
379 | b32b5995 | Giorgos Korfiatis | **POST** /astakos/api/commissions/<serial>/action |
380 | b32b5995 | Giorgos Korfiatis | |
381 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
382 | b32b5995 | Giorgos Korfiatis | Request Header Name Value |
383 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
384 | b32b5995 | Giorgos Korfiatis | X-Auth-Token Service authentication token |
385 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
386 | b32b5995 | Giorgos Korfiatis | |
387 | 2cb83537 | Giorgos Korfiatis | With this call a service can *accept* or *reject* a pending commission, that |
388 | 2cb83537 | Giorgos Korfiatis | is, finalize the registered usage or undo commission issued. |
389 | 2cb83537 | Giorgos Korfiatis | The system guarantees that a commission can always be later accepted |
390 | 2cb83537 | Giorgos Korfiatis | or rejected, no matter what other commissions have taken place in the meantime. |
391 | b32b5995 | Giorgos Korfiatis | |
392 | 2cb83537 | Giorgos Korfiatis | To accept, include in the request body a field indexed by ``accept``; |
393 | 2cb83537 | Giorgos Korfiatis | likewise for rejecting. |
394 | b32b5995 | Giorgos Korfiatis | |
395 | b32b5995 | Giorgos Korfiatis | **Example Requests**: |
396 | b32b5995 | Giorgos Korfiatis | |
397 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
398 | b32b5995 | Giorgos Korfiatis | |
399 | b32b5995 | Giorgos Korfiatis | { |
400 | b32b5995 | Giorgos Korfiatis | "accept": "" |
401 | b32b5995 | Giorgos Korfiatis | } |
402 | b32b5995 | Giorgos Korfiatis | |
403 | b32b5995 | Giorgos Korfiatis | { |
404 | b32b5995 | Giorgos Korfiatis | "reject": "" |
405 | b32b5995 | Giorgos Korfiatis | } |
406 | b32b5995 | Giorgos Korfiatis | |
407 | 2cb83537 | Giorgos Korfiatis | **Response Codes**: |
408 | 2cb83537 | Giorgos Korfiatis | |
409 | 2cb83537 | Giorgos Korfiatis | ====== ============================ |
410 | 2cb83537 | Giorgos Korfiatis | Status Description |
411 | 2cb83537 | Giorgos Korfiatis | ====== ============================ |
412 | 2cb83537 | Giorgos Korfiatis | 200 Success |
413 | 2cb83537 | Giorgos Korfiatis | 401 Unauthorized (Missing token) |
414 | 2cb83537 | Giorgos Korfiatis | 404 Commission Not Found |
415 | 2cb83537 | Giorgos Korfiatis | 500 Internal Server Error |
416 | 2cb83537 | Giorgos Korfiatis | ====== ============================ |
417 | 2cb83537 | Giorgos Korfiatis | |
418 | b32b5995 | Giorgos Korfiatis | Accept or Reject Multiple Commissions |
419 | b32b5995 | Giorgos Korfiatis | ..................................... |
420 | b32b5995 | Giorgos Korfiatis | |
421 | b32b5995 | Giorgos Korfiatis | **POST** /astakos/api/commissions/action |
422 | b32b5995 | Giorgos Korfiatis | |
423 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
424 | b32b5995 | Giorgos Korfiatis | Request Header Name Value |
425 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
426 | b32b5995 | Giorgos Korfiatis | X-Auth-Token Service authentication token |
427 | b32b5995 | Giorgos Korfiatis | ==================== ============================ |
428 | b32b5995 | Giorgos Korfiatis | |
429 | 2cb83537 | Giorgos Korfiatis | This allows to accept and reject multiple commissions in the same time, |
430 | 2cb83537 | Giorgos Korfiatis | by including the list of serials to accept and the list of serials to reject |
431 | 2cb83537 | Giorgos Korfiatis | in the request body. |
432 | b32b5995 | Giorgos Korfiatis | |
433 | b32b5995 | Giorgos Korfiatis | **Example Request**: |
434 | b32b5995 | Giorgos Korfiatis | |
435 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
436 | b32b5995 | Giorgos Korfiatis | |
437 | b32b5995 | Giorgos Korfiatis | { |
438 | b32b5995 | Giorgos Korfiatis | "accept": [56, 57], |
439 | b32b5995 | Giorgos Korfiatis | "reject": [56, 58, 59] |
440 | b32b5995 | Giorgos Korfiatis | } |
441 | b32b5995 | Giorgos Korfiatis | |
442 | 2cb83537 | Giorgos Korfiatis | The response includes the list of serials that have been actually |
443 | 2cb83537 | Giorgos Korfiatis | ``accepted`` or ``rejected`` and those that ``failed``. The latter |
444 | 2cb83537 | Giorgos Korfiatis | consists of a list of pairs. The first element of the pair is a serial |
445 | 2cb83537 | Giorgos Korfiatis | that failed, the second element is a cloudFault describing the failure. |
446 | 2cb83537 | Giorgos Korfiatis | |
447 | 2cb83537 | Giorgos Korfiatis | **Response Codes**: |
448 | 2cb83537 | Giorgos Korfiatis | |
449 | 2cb83537 | Giorgos Korfiatis | ====== ============================ |
450 | 2cb83537 | Giorgos Korfiatis | Status Description |
451 | 2cb83537 | Giorgos Korfiatis | ====== ============================ |
452 | 2cb83537 | Giorgos Korfiatis | 200 Success |
453 | 2cb83537 | Giorgos Korfiatis | 401 Unauthorized (Missing token) |
454 | 2cb83537 | Giorgos Korfiatis | 500 Internal Server Error |
455 | 2cb83537 | Giorgos Korfiatis | ====== ============================ |
456 | 2cb83537 | Giorgos Korfiatis | |
457 | b32b5995 | Giorgos Korfiatis | **Example Successful Response**: |
458 | b32b5995 | Giorgos Korfiatis | |
459 | b32b5995 | Giorgos Korfiatis | .. code-block:: javascript |
460 | b32b5995 | Giorgos Korfiatis | |
461 | b32b5995 | Giorgos Korfiatis | { "accepted": [57], |
462 | b32b5995 | Giorgos Korfiatis | "rejected": [59], |
463 | b32b5995 | Giorgos Korfiatis | "failed": [ |
464 | b32b5995 | Giorgos Korfiatis | [56, { |
465 | b32b5995 | Giorgos Korfiatis | "badRequest": { |
466 | b32b5995 | Giorgos Korfiatis | "message": "cannot both accept and reject serial 56", |
467 | b32b5995 | Giorgos Korfiatis | "code": 400 |
468 | b32b5995 | Giorgos Korfiatis | } |
469 | b32b5995 | Giorgos Korfiatis | } |
470 | b32b5995 | Giorgos Korfiatis | ], |
471 | b32b5995 | Giorgos Korfiatis | [58, { |
472 | b32b5995 | Giorgos Korfiatis | "itemNotFound": { |
473 | b32b5995 | Giorgos Korfiatis | "message": "serial 58 does not exist", |
474 | b32b5995 | Giorgos Korfiatis | "code": 404 |
475 | b32b5995 | Giorgos Korfiatis | } |
476 | b32b5995 | Giorgos Korfiatis | } |
477 | b32b5995 | Giorgos Korfiatis | ] |
478 | b32b5995 | Giorgos Korfiatis | ] |
479 | b32b5995 | Giorgos Korfiatis | } |