Statistics
| Branch: | Tag: | Revision:

root / docs / project-api-guide.rst @ d9fca80b

History | View | Annotate | Download (9.3 kB)

1
Projects
2
--------
3

    
4
Astakos allows users to create *projects*. Through a project, one can ask for
5
additional resources on the virtual infrastructure for a certain amount of
6
time. All users admitted to the project gain access to these resources.
7

    
8

    
9
Retrieve List of Projects
10
.........................
11

    
12
**GET** /account/v1.0/projects
13

    
14
Returns all accessible projects. See below.
15

    
16
====================  =========================
17
Request Header Name   Value
18
====================  =========================
19
X-Auth-Token          User authentication token
20
====================  =========================
21

    
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.
29

    
30
**Example Request**:
31

    
32
.. code-block:: javascript
33

    
34
GET /account/v1.0/projects?state=active&owner=uuid
35

    
36
**Response Codes**:
37

    
38
======  =====================
39
Status  Description
40
======  =====================
41
200     Success
42
400     Bad Request
43
401     Unauthorized (Missing token)
44
500     Internal Server Error
45
======  =====================
46

    
47
**Example Successful Response**:
48

    
49
List of project details. See below.
50

    
51
Retrieve a Project
52
..................
53

    
54
**GET** /account/v1.0/projects/<proj_id>
55

    
56
====================  =========================
57
Request Header Name   Value
58
====================  =========================
59
X-Auth-Token          User authentication token
60
====================  =========================
61

    
62
A project is accessible when the request user is admin, project owner,
63
applicant or member, or the project is active.
64

    
65
**Response Codes**:
66

    
67
======  ============================
68
Status  Description
69
======  ============================
70
200     Success
71
401     Unauthorized (Missing token)
72
403     Forbidden
73
404     Not Found
74
500     Internal Server Error
75
======  ============================
76

    
77
**Example Successful Response**:
78

    
79
.. code-block:: javascript
80

    
81
  {
82
      "id": proj_id,
83
      "state": "uninitialized" | "active" | "suspended" | "terminated" | "deleted",
84
      "creation_date": "2013-06-26T11:48:06.579100+00:00",
85
      "name": "name",
86
      "owner": uuid,
87
      "homepage": homepage,
88
      "description": description,
89
      "end_date": date,
90
      "join_policy": "auto" | "moderated" | "closed",
91
      "leave_policy": "auto" | "moderated" | "closed",
92
      "max_members": natural number
93
      "resources": {"cyclades.vm": {"project_capacity": int,
94
                                    "member_capacity": int
95
                                   }
96
                   }
97
      "last_application": last application or null,
98
      "deactivation_date": date  # if applicable
99
  }
100

    
101
Create a Project
102
................
103

    
104
**POST** /account/v1.0/projects
105

    
106
====================  =========================
107
Request Header Name   Value
108
====================  =========================
109
X-Auth-Token          User authentication token
110
====================  =========================
111

    
112
**Example Request**:
113

    
114
.. code-block:: javascript
115

    
116
  {
117
      "name": name,
118
      "owner": uuid,  # if omitted, request user assumed
119
      "homepage": homepage,  # optional
120
      "description": description,  # optional
121
      "comments": comments,  # optional
122
      "start_date": date,  # optional
123
      "end_date": date,
124
      "join_policy": "auto" | "moderated" | "closed",  # default: "moderated"
125
      "leave_policy": "auto" | "moderated" | "closed",  # default: "auto"
126
      "resources": {"cyclades.vm": {"project_capacity": int,
127
                                    "member_capacity": int
128
                                   }
129
                   }
130
  }
131

    
132
**Response Codes**:
133

    
134
======  ============================
135
Status  Description
136
======  ============================
137
201     Created
138
400     Bad Request
139
401     Unauthorized (Missing token)
140
403     Forbidden
141
409     Conflict
142
500     Internal Server Error
143
======  ============================
144

    
145
**Example Successful Response**:
146

    
147
.. code-block:: javascript
148

    
149
  {
150
      "id": project_id,
151
      "application": application_id
152
  }
153

    
154

    
155
Modify a Project
156
................
157

    
158
**PUT** /account/v1.0/projects/<proj_id>
159

    
160
====================  =========================
161
Request Header Name   Value
162
====================  =========================
163
X-Auth-Token          User authentication token
164
====================  =========================
165

    
166

    
167
**Example Request**:
168

    
169
As above.
170

    
171
**Response Codes**:
172

    
173
======  ============================
174
Status  Description
175
======  ============================
176
201     Created
177
400     Bad Request
178
401     Unauthorized (Missing token)
179
403     Forbidden
180
404     Not Found
181
409     Conflict
182
500     Internal Server Error
183
======  ============================
184

    
185
**Example Successful Response**:
186

    
187
As above.
188

    
189
Take Action on a Project
190
........................
191

    
192
**POST** /account/v1.0/projects/<proj_id>/action
193

    
194
====================  =========================
195
Request Header Name   Value
196
====================  =========================
197
X-Auth-Token          User authentication token
198
====================  =========================
199

    
200
**Example Request**:
201

    
202
.. code-block:: javascript
203

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

    
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``.
213

    
214
**Response Codes**:
215

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

    
228
Retrieve List of Memberships
229
............................
230

    
231
**GET** /account/v1.0/projects/memberships
232

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

    
239
Get all accessible memberships. Filtering by project is possible via the GET
240
parameter ``project``.
241

    
242
**Response Codes**:
243

    
244
======  ============================
245
Status  Description
246
======  ============================
247
200     Success
248
400     Bad Request
249
401     Unauthorized (Missing token)
250
500     Internal Server Error
251
======  ============================
252

    
253
**Example Successful Response**
254

    
255
List of memberships. See below.
256

    
257
Retrieve a Membership
258
.....................
259

    
260
**GET** /account/v1.0/projects/memberships/<memb_id>
261

    
262
====================  ============================
263
Request Header Name   Value
264
====================  ============================
265
X-Auth-Token          User authentication token
266
====================  ============================
267

    
268
A membership is accessible if the request user is admin, project owner or
269
the member.
270

    
271
**Response Codes**:
272

    
273
======  ============================
274
Status  Description
275
======  ============================
276
200     Success
277
401     Unauthorized (Missing token)
278
403     Forbidden
279
404     Not Found
280
500     Internal Server Error
281
======  ============================
282

    
283
**Example Successful Response**
284

    
285
.. code-block:: javascript
286

    
287
  {
288
      "id": id,
289
      "user": uuid,
290
      "project": project_id,
291
      "state": "requested" | "accepted" | "leave_requested" | "suspended" | "rejected" | "cancelled" | "removed",
292
      "requested": last_request_date,
293
      "accepted": last_acceptance_date,
294
      "removed": last_removal_date,
295
      "allowed_actions": ["leave", "cancel", "accept", "reject", "remove"],
296
  }
297

    
298
Take Action on a Membership
299
...........................
300

    
301
**POST** /account/v1.0/projects/memberships/<memb_id>/action
302

    
303
====================  ============================
304
Request Header Name   Value
305
====================  ============================
306
X-Auth-Token          User authentication token
307
====================  ============================
308

    
309
**Example Request**
310

    
311
.. code-block:: javascript
312

    
313
  {
314
      <action>: "reason"
315
  }
316

    
317
<action> can be one of: "leave", "cancel", "accept", "reject", "remove"
318

    
319
**Response Codes**:
320

    
321
======  ============================
322
Status  Description
323
======  ============================
324
200     Success
325
400     Bad Request
326
401     Unauthorized (Missing token)
327
403     Forbidden
328
404     Not Found
329
409     Conflict
330
500     Internal Server Error
331
======  ============================
332

    
333
Create a Membership
334
...................
335

    
336
**POST** /account/v1.0/projects/memberships
337

    
338
====================  ============================
339
Request Header Name   Value
340
====================  ============================
341
X-Auth-Token          User authentication token
342
====================  ============================
343

    
344
**Example Requests**
345

    
346
.. code-block:: javascript
347

    
348
  {
349
      "join": {
350
          "project": proj_id
351
      }
352
  }
353

    
354
.. code-block:: javascript
355

    
356
  {
357
      "enroll": {
358
          "project": proj_id,
359
          "user": "user@example.org"
360
      }
361
  }
362

    
363
**Response Codes**:
364

    
365
======  ============================
366
Status  Description
367
======  ============================
368
200     Success
369
400     Bad Request
370
401     Unauthorized (Missing token)
371
403     Forbidden
372
409     Conflict
373
500     Internal Server Error
374
======  ============================
375

    
376
**Example Response**
377

    
378
.. code-block:: javascript
379

    
380
  {
381
      "id": membership_id
382
  }