Revision 949f8393 docs/astakos-api-guide.rst

b/docs/astakos-api-guide.rst
20 20
=========================  ================================
21 21
Revision                   Description
22 22
=========================  ================================
23
0.6 (June 06, 2012)        Split service and admin API.
23 24
0.1 (Feb 10, 2012)         Initial release.
24 25
=========================  ================================
25 26

  
26
API Operations
27
--------------
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.
28 33

  
29 34
.. _authenticate-api-label:
30 35

  
......
59 64
auth_token_created           Token creation date
60 65
has_credits                  Whether user has credits
61 66
has_signed_terms             Whether user has aggred on terms
67
groups                       User groups
62 68
===========================  ============================
63 69

  
64 70
Example reply:
......
66 72
::
67 73

  
68 74
  {"username": "4ad9f34d6e7a4992b34502d40f40cb",
69
  "uniq": "papagian@example.com"
75
  "uniq": "user@example.com"
70 76
  "auth_token": "0000",
71
  "auth_token_expires": "Tue, 11-Sep-2012 09:17:14 ",
72
  "auth_token_created": "Sun, 11-Sep-2011 09:17:14 ",
77
  "auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT",
78
  "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
73 79
  "has_credits": false,
74 80
  "has_signed_terms": true}
75 81

  
......
79 85
Return Code                 Description
80 86
=========================== =====================
81 87
204 (No Content)            The request succeeded
82
400 (Bad Request)           The request is invalid
88
400 (Bad Request)           Method not allowed or no user found
83 89
401 (Unauthorized)          Missing token or inactive user or penging approval terms
84 90
500 (Internal Server Error) The request cannot be completed because of an internal error
85 91
=========================== =====================
86 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

  
87 197
Get Services
88 198
^^^^^^^^^^^^
89 199

  
......
99 209

  
100 210
::
101 211

  
102
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "cloud"},
103
 {"url": "/okeanos.html", "name": "~okeanos", "id": "okeanos"},
104
 {"url": "/ui/", "name": "pithos+", "id": "pithos"}]
105
 
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

  
106 217
Get Menu
107 218
^^^^^^^^
108 219

  
......
114 225
``/im/get_menu``     GET        Get cloud bar menu
115 226
==================== =========  ==================
116 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

  
117 268
|
118 269

  
119 270
======================  =========================
120 271
Request Parameter Name  Value
121 272
======================  =========================
122
location                Location to pass in the next parameter
273
auth_token              User token
274
feedback_msg            Feedback message
275
feedback_data           Additional information about service client status
123 276
======================  =========================
124 277

  
125
Example reply if request user is not authenticated:
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:
126 329

  
127 330
::
128 331

  
129
[{"url": "/im/login?next=", "name": "login..."}]
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
^^^^^^^^^^^^^^^^^^^^
130 345

  
131
Example reply if request user is authenticated::
346
Returns a json formatted dictionary containing information about a specific user
132 347

  
133
    [{"url": "/im/profile", "name": "user@grnet.gr"},
134
     {"url": "/im/profile", "name": "view your profile..."},
135
     {"url": "/im/password", "name": "change your password..."},
136
     {"url": "/im/feedback", "name": "feedback..."},
137
     {"url": "/im/logout", "name": "logout..."}]
348
========================================== =========  ==================
349
Uri                                        Method     Description
350
========================================== =========  ==================
351
``/im/service/api/v2.0/users/{username}``  GET        Get user information by username
352
========================================== =========  ==================
353

  
354
|
138 355

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

  
362
|
140 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
::
141 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}

Also available in: Unified diff