Revision 0f2bd3f9

b/docs/project-api-guide.rst
19 19
X-Auth-Token          User authentication token
20 20
====================  =========================
21 21

  
22
Request can specify a filter.
22
The request can include the following filters as GET parameters:
23
``state``, ``owner``, ``name``.
24

  
25
It also supports parameter ``mode`` with possible values: ``member``,
26
``default``. The former restricts the result to active projects where the
27
request user is an active member. By default it returns all accessible
28
projects; see below.
23 29

  
24 30
**Example Request**:
25 31

  
26 32
.. code-block:: javascript
27 33

  
28
  {
29
      "filter": {
30
          "state": ["active", "suspended"],
31
          "owner": [uuid]
32
      }
33
  }
34
GET /account/v1.0/projects?state=active&owner=uuid
34 35

  
35 36
**Response Codes**:
36 37

  
......
79 80

  
80 81
  {
81 82
      "id": proj_id,
82
      "application": app_id,
83
      "state": "pending" | "active" | "denied" | "dismissed" | "cancelled" | "suspended" | "terminated",
83
      "state": "uninitialized" | "active" | "suspended" | "terminated" | "deleted",
84 84
      "creation_date": "2013-06-26T11:48:06.579100+00:00",
85 85
      "name": "name",
86 86
      "owner": uuid,
87
      "homepage": homepage or null,
88
      "description": description or null,
89
      "start_date": date,
87
      "homepage": homepage,
88
      "description": description,
90 89
      "end_date": date,
91 90
      "join_policy": "auto" | "moderated" | "closed",
92 91
      "leave_policy": "auto" | "moderated" | "closed",
93 92
      "max_members": natural number
94
      "resources": {"cyclades.vm": {"project_capacity": int or null,
93
      "resources": {"cyclades.vm": {"project_capacity": int,
95 94
                                    "member_capacity": int
96 95
                                   }
97 96
                   }
98
      # only if request user is admin or project owner:
99
      "comments": comments,
100
      "pending_application": last pending app id or null,
97
      "last_application": last application or null,
101 98
      "deactivation_date": date  # if applicable
102 99
  }
103 100

  
......
126 123
      "end_date": date,
127 124
      "join_policy": "auto" | "moderated" | "closed",  # default: "moderated"
128 125
      "leave_policy": "auto" | "moderated" | "closed",  # default: "auto"
129
      "resources": {"cyclades.vm": {"project_capacity": int or null,
126
      "resources": {"cyclades.vm": {"project_capacity": int,
130 127
                                    "member_capacity": int
131 128
                                   }
132 129
                   }
......
205 202
.. code-block:: javascript
206 203

  
207 204
  {
208
      <action>: "reason"
209
  }
210

  
211
<action> can be: "suspend", "unsuspend", "terminate", "reinstate"
212

  
213
**Response Codes**:
214

  
215
======  ============================
216
Status  Description
217
======  ============================
218
200     Success
219
400     Bad Request
220
401     Unauthorized (Missing token)
221
403     Forbidden
222
404     Not Found
223
409     Conflict
224
500     Internal Server Error
225
======  ============================
226

  
227
Retrieve List of Applications
228
.............................
229

  
230
**GET** /account/v1.0/projects/apps
231

  
232
====================  =========================
233
Request Header Name   Value
234
====================  =========================
235
X-Auth-Token          User authentication token
236
====================  =========================
237

  
238
Get all accessible applications. See below.
239

  
240
**Example optional request**
241

  
242
.. code-block:: javascript
243

  
244
  {
245
      "project": <project_id>
246
  }
247

  
248
**Response Codes**:
249

  
250
======  ============================
251
Status  Description
252
======  ============================
253
200     Success
254
400     Bad Request
255
401     Unauthorized (Missing token)
256
500     Internal Server Error
257
======  ============================
258

  
259
**Example Successful Response**:
260

  
261
List of application details. See below.
262

  
263
Retrieve an Application
264
.......................
265

  
266
**GET** /account/v1.0/projects/apps/<app_id>
267

  
268
====================  =========================
269
Request Header Name   Value
270
====================  =========================
271
X-Auth-Token          User authentication token
272
====================  =========================
273

  
274
An application is accessible when the request user is admin or the
275
application owner/applicant.
276

  
277
**Response Codes**:
278

  
279
======  ============================
280
Status  Description
281
======  ============================
282
200     Success
283
401     Unauthorized (Missing token)
284
403     Forbidden
285
404     Not Found
286
500     Internal Server Error
287
======  ============================
288

  
289
**Example Successful Response**
290

  
291
.. code-block:: javascript
292

  
293
  {
294
      "id": app_id,
295
      "project": project_id,
296
      "state": "pending" | "approved" | "replaced" | "denied" | "dismissed" | "cancelled",
297
      "name": "name",
298
      "owner": uuid,
299
      "applicant": uuid,
300
      "homepage": homepage or null,
301
      "description": description or null,
302
      "start_date": date,
303
      "end_date": date,
304
      "join_policy": "auto" | "moderated" | "closed",
305
      "leave_policy": "auto" | "moderated" | "closed",
306
      "max_members": int or null
307
      "comments": comments,
308
      "resources": {"cyclades.vm": {"project_capacity": int or null,
309
                                    "member_capacity": int
310
                                   }
311
                   }
312
  }
313

  
314
Take Action on an Application
315
.............................
316

  
317
**POST** /account/v1.0/projects/apps/<app_id>/action
318

  
319
====================  ============================
320
Request Header Name   Value
321
====================  ============================
322
X-Auth-Token          User authentication token
323
====================  ============================
324

  
325
**Example Request**:
326

  
327
.. code-block:: javascript
328

  
329
  {
330
      <action>: "reason"
205
      <action>: {"reason": reason,
206
                 "app_id": app_id  # only for app related actions
207
                }
331 208
  }
332 209

  
333
<action> can be one of "approve", "deny", "dismiss", "cancel".
210
<action> can be: "suspend", "unsuspend", "terminate", "reinstate",
211
"approve", "deny", "dismiss", "cancel". The last four actions operate on the
212
project's last application and require its ``app_id``.
334 213

  
335 214
**Response Codes**:
336 215

  
......
357 236
X-Auth-Token          User authentication token
358 237
====================  ============================
359 238

  
360
Get all accessible memberships. See below.
361

  
362
**Example Optional Request**
363

  
364
.. code-block:: javascript
365

  
366
  {
367
      "project": <proj_id>
368
  }
239
Get all accessible memberships. Filtering by project is possible via the GET
240
parameter ``project``.
369 241

  
370 242
**Response Codes**:
371 243

  
b/docs/quota-api-guide.rst
49 49

  
50 50
The system specifies user quotas for each available resource. Resources
51 51
can be allocated from various sources. By default, users get resources
52
from a single source, called ``system``. For each combination of user,
52
from their user-specific `base projects', which are identified by the same
53
uuid as the users. For each combination of user,
53 54
source, and resource, the quota system keeps track of the maximum allowed
54 55
value (limit) and the current actual usage. The former is controlled by
55 56
the policy defined in Astakos; the latter is updated by the services that
......
69 70

  
70 71
A user can query their resources with this call. It returns in a nested
71 72
dictionary structure, for each source and resource, three indicators.
72
``limit`` and ``usage`` are as explained above. ``pending`` is related to the
73
commissioning system explained below. Roughly, if ``pending`` is non zero,
74
this indicates that some resource allocation process has started but not
75
finished properly.
73
``limit`` and ``usage`` are as explained above. ``pending`` is related to
74
the commissioning system explained below. Roughly, if ``pending`` is non
75
zero, this indicates that some resource allocation process has started but
76
not finished properly. The project-level indicators ``project_limit``,
77
``project_usage`` and ``project_pending`` are included in the resource
78
dictionaries, too. The project quota must be taken into account in order to
79
compute the `effective` quota limit::
80

  
81
  taken_by_others = project_usage - usage
82
  effective_limit = min(limit, project_limit - taken_by_others)
76 83

  
77 84
**Response Codes**:
78 85

  
......
89 96
.. code-block:: javascript
90 97

  
91 98
  {
92
      "system": {
99
      "base_project_id": {
93 100
          "cyclades.ram": {
94 101
              "usage": 536870912,
95 102
              "limit": 1073741824,
96
              "pending": 0
103
              "pending": 0,
104
              "project_usage": 536870912,
105
              "project_limit": 1073741824,
106
              "project_pending": 0
97 107

  
98 108
          },
99 109
          "cyclades.vm": {
100 110
              "usage": 2,
101 111
              "limit": 2,
102
              "pending": 0
112
              "pending": 0,
113
              "project_usage": 2,
114
              "project_limit: 2,
115
              "project_pending": 0
103 116
          }
104 117
      },
105 118
      "project:1": {
106 119
          "cyclades.ram": {
107 120
              "usage": 2147483648,
108 121
              "limit": 2147483648,
109
              "pending": 0
122
              "pending": 0,
123
              "project_usage": 4147483648,
124
              "project_limit": 14147483648,
125
              "project_pending": 0
110 126
          },
111 127
          "cyclades.vm": {
112 128
              "usage": 2,
113 129
              "limit": 5,
114
              "pending": 1
130
              "pending": 1,
131
              "project_usage": 4,
132
              "project_limit": 10,
133
              "project_pending": 1
115 134
          }
116 135
      }
117 136
  }
......
127 146
X-Auth-Token          Service authentication token
128 147
====================  ============================
129 148

  
130
A service can query the quotas for all resources related to it. By default,
131
it returns the quotas for all users, in the format explained above, indexed
132
by the user identifier (UUID).
149
A service can query the user quotas for all resources related to it. By
150
default, it returns the quotas for all users, in the format explained above,
151
indexed by the user identifier (UUID).
133 152

  
134 153
Use the GET parameter ``?user=<uuid>`` to query for a single user.
135 154

  
......
150 169

  
151 170
  {
152 171
      "1a6165d0-5020-4b6d-a4ad-83476632a584": {
153
          "system": {
172
          "base_project_id": {
154 173
              "cyclades.ram": {
155 174
                  "usage": 536870912,
156 175
                  "limit": 1073741824,
157
                  "pending": 0
176
                  "pending": 0,
177
                  "project_usage": 536870912,
178
                  "project_limit": 1073741824,
179
                  "project_pending": 0
158 180
              },
159 181
              "cyclades.vm": {
160 182
                  "usage": 2,
161 183
                  "limit": 2,
162
                  "pending": 0
184
                  "pending": 0,
185
                  "project_usage": 2,
186
                  "project_limit: 2,
187
                  "project_pending": 0
163 188
              }
164 189
          },
165 190
          "project:1": {
166 191
              "cyclades.ram": {
167 192
                  "usage": 2147483648,
168 193
                  "limit": 2147483648,
169
                  "pending": 0
194
                  "pending": 0,
195
                  "project_usage": 4147483648,
196
                  "project_limit": 14147483648,
197
                  "project_pending": 0
170 198
              },
171 199
              "cyclades.vm": {
172 200
                  "usage": 2,
173 201
                  "limit": 5,
174
                  "pending": 1
202
                  "pending": 1,
203
                  "project_usage": 4,
204
                  "project_limit": 10,
205
                  "project_pending": 1
175 206
              }
176 207
          }
177 208
      }
178 209
  }
179 210

  
211
**GET** /account/v1.0/service_project_quotas
212

  
213
====================  ============================
214
Request Header Name   Value
215
====================  ============================
216
X-Auth-Token          Service authentication token
217
====================  ============================
218

  
219
A service can also query the project quotas for all resources related to it.
220
By default, it returns the quotas for all projects, in the format explained
221
above, indexed by the project identifier (UUID).
222

  
223
Use the GET parameter ``?project=<uuid>`` to query for a single project.
224

  
225

  
226
**Response Codes**:
227

  
228
======  ============================
229
Status  Description
230
======  ============================
231
200     Success
232
401     Unauthorized (Missing token)
233
500     Internal Server Error
234
======  ============================
235

  
236
**Example Successful Response**:
237

  
238
.. code-block:: javascript
239

  
240
  {
241
      "base_project_id": {
242
          "cyclades.ram": {
243
              "project_usage": 536870912,
244
              "project_limit": 1073741824,
245
              "project_pending": 0
246
          },
247
          "cyclades.vm": {
248
              "project_usage": 2,
249
              "project_limit: 2,
250
              "project_pending": 0
251
          }
252
      },
253
      "base_project2_id": {
254
          "cyclades.ram": {
255
              "project_usage": 0,
256
              "project_limit": 1073741824,
257
              "project_pending": 0
258
          },
259
          "cyclades.vm": {
260
              "project_usage": 0,
261
              "project_limit: 2,
262
              "project_pending": 0
263
          }
264
      },
265
      "project:1": {
266
          "cyclades.ram": {
267
              "project_usage": 4147483648,
268
              "project_limit": 14147483648,
269
              "project_pending": 0
270
          },
271
          "cyclades.vm": {
272
              "project_usage": 4,
273
              "project_limit": 10,
274
              "project_pending": 1
275
          }
276
      }
277
  }
278

  
180 279
Commissions
181 280
-----------
182 281

  
......
203 302
X-Auth-Token          Service authentication token
204 303
====================  ============================
205 304

  
206
A service issues a commission by providing a list of *provisions*, i.e.
207
the intended allocation for a particular user (in general, ``holder``),
208
``source``, and ``resource`` combination.
305
A service issues a commission by providing a list of *provisions*, i.e. the
306
intended allocation for a particular user and project (in general,
307
``holder``), ``source``, and ``resource`` combination. Users must be
308
specified with ``user:<uuid>`` and projects with ``project:<uuid>``. When
309
charging a user/project pair for a given resource, the intended use is to
310
also charge the project separately (by including a provision with the
311
project as holder and ``null`` as source), as in the example below.
209 312

  
210 313
The request body consists of a JSON dict (as in the example below), which
211 314
apart from the provisions list can also contain the following optional
......
225 328
      "name": "an optional description",
226 329
      "provisions": [
227 330
          {
228
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
229
              "source": "system",
331
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
332
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
333
              "resource": "cyclades.vm",
334
              "quantity": 1
335
          },
336
          {
337
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
338
              "source": null,
230 339
              "resource": "cyclades.vm",
231 340
              "quantity": 1
232 341
          },
233 342
          {
234
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
235
              "source": "system",
343
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
344
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
345
              "resource": "cyclades.ram",
346
              "quantity": 536870912
347
          },
348
          {
349
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
350
              "source": null,
236 351
              "resource": "cyclades.ram",
237 352
              "quantity": 536870912
238 353
          }
......
279 394
          "code": 413,
280 395
          "data": {
281 396
              "provision": {
282
                  "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
283
                  "source": "system",
397
                  "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
398
                  "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
284 399
                  "resource": "cyclades.vm",
285 400
                  "quantity": 1
286 401
              },
......
357 472
      "name": "an optional description",
358 473
      "provisions": [
359 474
          {
360
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
361
              "source": "system",
475
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
476
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
362 477
              "resource": "cyclades.vm",
363 478
              "quantity": 1
364 479
          },
365 480
          {
366
              "holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad",
367
              "source": "system",
481
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
482
              "source": null,
483
              "resource": "cyclades.vm",
484
              "quantity": 1
485
          },
486
          {
487
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
488
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
489
              "resource": "cyclades.ram",
490
              "quantity": 536870912
491
          },
492
          {
493
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
494
              "source": null,
368 495
              "resource": "cyclades.ram",
369 496
              "quantity": 536870912
370 497
          }

Also available in: Unified diff