Statistics
| Branch: | Tag: | Revision:

root / docs / astakos-api-guide.rst @ 949f8393

History | View | Annotate | Download (12.7 kB)

1
Astakos API 
2
===========
3

    
4
This is Astakos API guide.
5

    
6
Overview
7
--------
8

    
9

    
10
Astakos service co-ordinates the access to resources (and the subsequent
11
permission model) and acts as the single point of registry and entry to the
12
GRNET cloud services.
13

    
14
This document's goals is to describe the APIs to the outer world.
15
Make sure you have read the :ref:`astakos` general architecture first.
16

    
17
Document Revisions
18
^^^^^^^^^^^^^^^^^^
19

    
20
=========================  ================================
21
Revision                   Description
22
=========================  ================================
23
0.6 (June 06, 2012)        Split service and admin API.
24
0.1 (Feb 10, 2012)         Initial release.
25
=========================  ================================
26

    
27
Admin API Operations
28
--------------------
29

    
30
The operations described in this chapter allow users to authenticate themselves and priviledged users (ex. helpdesk) to access other user information.
31

    
32
Most of the operations require a valid token assigned to users having the necessary permissions.
33

    
34
.. _authenticate-api-label:
35

    
36
Authenticate
37
^^^^^^^^^^^^
38

    
39
Authenticate API requests require a token. An application that wishes to connect to Astakos, but does not have a token, should redirect the user to ``/login``. (see :ref:`authentication-label`)
40

    
41
==================== =========  ==================
42
Uri                  Method     Description
43
==================== =========  ==================
44
``/im/authenticate`` GET        Authenticate user using token
45
==================== =========  ==================
46

    
47
|
48

    
49
====================  ===========================
50
Request Header Name   Value
51
====================  ===========================
52
X-Auth-Token          Authentication token
53
====================  ===========================
54

    
55
Extended information on the user serialized in the json format will be returned:
56

    
57
===========================  ============================
58
Name                         Description
59
===========================  ============================
60
username                     User uniq identifier
61
uniq                         User email (uniq identifier used by Astakos)
62
auth_token                   Authentication token
63
auth_token_expires           Token expiration date
64
auth_token_created           Token creation date
65
has_credits                  Whether user has credits
66
has_signed_terms             Whether user has aggred on terms
67
groups                       User groups
68
===========================  ============================
69

    
70
Example reply:
71

    
72
::
73

    
74
  {"username": "4ad9f34d6e7a4992b34502d40f40cb",
75
  "uniq": "user@example.com"
76
  "auth_token": "0000",
77
  "auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT",
78
  "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
79
  "has_credits": false,
80
  "has_signed_terms": true}
81

    
82
|
83

    
84
=========================== =====================
85
Return Code                 Description
86
=========================== =====================
87
204 (No Content)            The request succeeded
88
400 (Bad Request)           Method not allowed or no user found
89
401 (Unauthorized)          Missing token or inactive user or penging approval terms
90
500 (Internal Server Error) The request cannot be completed because of an internal error
91
=========================== =====================
92

    
93
Get User by email
94
^^^^^^^^^^^^^^^^^
95

    
96
Returns a json formatted dictionary containing information about a specific user
97

    
98
============================== =========  ==================
99
Uri                            Method     Description
100
============================== =========  ==================
101
``/im/admin/api/v2.0/users/``  GET        Get user information by email
102
============================== =========  ==================
103

    
104
|
105

    
106
====================  ===========================
107
Request Header Name   Value
108
====================  ===========================
109
X-Auth-Token          Authentication token owned by
110
                      a user has or inherits ``im.can_access_userinfo`` permission
111
====================  ===========================
112

    
113
|
114

    
115
======================  =========================
116
Request Parameter Name  Value
117
======================  =========================
118
name                    Email
119
======================  =========================
120

    
121

    
122
|
123

    
124
=========================== =====================
125
Return Code                 Description
126
=========================== =====================
127
200 (OK)                    The request succeeded
128
400 (Bad Request)           Method not allowed
129
401 (Unauthorized)          Missing or invalid token or unauthorized user
130
404 (Not Found)             Missing email or inactive user
131
500 (Internal Server Error) The request cannot be completed because of an internal error
132
=========================== =====================
133

    
134
Example reply:
135

    
136
::
137

    
138
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
139
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
140
    "name": "Firstname Surname",
141
    "groups": ["default"],
142
    "user_permissions": [],
143
    "has_credits": false,
144
    "auth_token_expires":"Fri, 29 Jun 2012 10:03:37 GMT",
145
    "enabled": true,
146
    "email": ["user@example.com"],
147
    "id": 4}
148

    
149
Get User by username
150
^^^^^^^^^^^^^^^^^^^^
151

    
152
Returns a json formatted dictionary containing information about a specific user
153

    
154
======================================== =========  ==================
155
Uri                                      Method     Description
156
======================================== =========  ==================
157
``/im/admin/api/v2.0/users/{username}``  GET        Get user information by username
158
======================================== =========  ==================
159

    
160
|
161

    
162
====================  ===========================
163
Request Header Name   Value
164
====================  ===========================
165
X-Auth-Token          Authentication token owned
166
                      by a user has or inherits ``im.can_access_userinfo`` permission
167
====================  ===========================
168

    
169
|
170

    
171
=========================== =====================
172
Return Code                 Description
173
=========================== =====================
174
200 (OK)                    The request succeeded
175
400 (Bad Request)           Method not allowed
176
401 (Unauthorized)          Missing or invalid token or unauthorized user
177
404 (Not Found)             Invalid username
178
500 (Internal Server Error) The request cannot be completed because of an internal error
179
=========================== =====================
180

    
181
Example reply:
182

    
183
::
184

    
185
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
186
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
187
    "name": "Firstname Surname",
188
    "groups": ["default"],
189
    "user_permissions": [],
190
    "has_credits": false,
191
    "auth_token_expires":
192
    "Fri, 29 Jun 2012 10:03:37 GMT",
193
    "enabled": true,
194
    "email": ["user@example.com"],
195
    "id": 4}
196

    
197
Get Services
198
^^^^^^^^^^^^
199

    
200
Returns a json formatted list containing information about the supported cloud services.
201

    
202
==================== =========  ==================
203
Uri                  Method     Description
204
==================== =========  ==================
205
``/im/get_services`` GET        Get cloud services
206
==================== =========  ==================
207

    
208
Example reply:
209

    
210
::
211

    
212
    [{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"},
213
    {"url": "/okeanos.html", "name": "~okeanos", "id": "2"},
214
    {"url": "/ui/", "name": "pithos+", "id": "3"}]
215

    
216

    
217
Get Menu
218
^^^^^^^^
219

    
220
Returns a json formatted list containing the cloud bar links. 
221

    
222
==================== =========  ==================
223
Uri                  Method     Description
224
==================== =========  ==================
225
``/im/get_menu``     GET        Get cloud bar menu
226
==================== =========  ==================
227

    
228
Example reply if request user is not authenticated:
229

    
230
::
231

    
232
    [{"url": "/im/", "name": "Sign in"}]
233

    
234
Example reply if request user is authenticated:
235

    
236
::
237

    
238
    [{"url": "/im/login", "name": "user@example.com"},
239
    {"url": "/im/profile", "name": "My account"},
240
    {"url": "/im/logout", "name": "Sign out"}]
241

    
242
Service API Operations
243
----------------------
244

    
245
The operations described in this chapter allow services to access user information and perform specific tasks.
246

    
247
The operations require a valid service token.
248

    
249
Send feedback
250
^^^^^^^^^^^^^
251

    
252
Via this operaton services can post user feedback requests.
253

    
254
========================= =========  ==================
255
Uri                       Method     Description
256
========================= =========  ==================
257
``/im/service/feedback``  POST       Send feedback
258
========================= =========  ==================
259

    
260
|
261

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

    
268
|
269

    
270
======================  =========================
271
Request Parameter Name  Value
272
======================  =========================
273
auth_token              User token
274
feedback_msg            Feedback message
275
feedback_data           Additional information about service client status
276
======================  =========================
277

    
278
|
279

    
280
=========================== =====================
281
Return Code                 Description
282
=========================== =====================
283
200 (OK)                    The request succeeded
284
400 (Bad Request)           Method not allowed or missing or invalid user token parameter or invalid message data
285
401 (Unauthorized)          Missing or expired service token
286
500 (Internal Server Error) The request cannot be completed because of an internal error
287
=========================== =====================
288

    
289
Get User by email
290
^^^^^^^^^^^^^^^^^
291

    
292
Returns a json formatted dictionary containing information about a specific user
293

    
294
================================ =========  ==================
295
Uri                              Method     Description
296
================================ =========  ==================
297
``/im/service/api/v2.0/users/``  GET        Get user information by email
298
================================ =========  ==================
299

    
300
|
301

    
302
====================  ============================
303
Request Header Name   Value
304
====================  ============================
305
X-Auth-Token          Service Authentication token
306
====================  ============================
307

    
308
|
309

    
310
======================  =========================
311
Request Parameter Name  Value
312
======================  =========================
313
name                    Email
314
======================  =========================
315

    
316
|
317

    
318
=========================== =====================
319
Return Code                 Description
320
=========================== =====================
321
200 (OK)                    The request succeeded
322
400 (Bad Request)           Method not allowed
323
401 (Unauthorized)          Missing or expired or invalid service token
324
404 (Not Found)             Missing email or inactive user
325
500 (Internal Server Error) The request cannot be completed because of an internal error
326
=========================== =====================
327

    
328
Example reply:
329

    
330
::
331

    
332
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
333
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
334
    "name": "Firstname Surname",
335
    "groups": ["default"],
336
    "user_permissions": [],
337
    "has_credits": false,
338
    "auth_token_expires":"Fri, 29 Jun 2012 10:03:37 GMT",
339
    "enabled": true,
340
    "email": ["user@example.com"],
341
    "id": 4}
342

    
343
Get User by username
344
^^^^^^^^^^^^^^^^^^^^
345

    
346
Returns a json formatted dictionary containing information about a specific user
347

    
348
========================================== =========  ==================
349
Uri                                        Method     Description
350
========================================== =========  ==================
351
``/im/service/api/v2.0/users/{username}``  GET        Get user information by username
352
========================================== =========  ==================
353

    
354
|
355

    
356
====================  ============================
357
Request Header Name   Value
358
====================  ============================
359
X-Auth-Token          Service Authentication token
360
====================  ============================
361

    
362
|
363

    
364
=========================== =====================
365
Return Code                 Description
366
=========================== =====================
367
200 (OK)                    The request succeeded
368
400 (Bad Request)           Method not allowed
369
401 (Unauthorized)          Missing or expired or invalid service token
370
404 (Not Found)             Invalid username
371
500 (Internal Server Error) The request cannot be completed because of an internal error
372
=========================== =====================
373

    
374
Example reply:
375

    
376
::
377

    
378
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
379
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
380
    "name": "Firstname Surname",
381
    "groups": ["default"],
382
    "user_permissions": [],
383
    "has_credits": false,
384
    "auth_token_expires":
385
    "Fri, 29 Jun 2012 10:03:37 GMT",
386
    "enabled": true,
387
    "email": ["user@example.com"],
388
    "id": 4}