root / docs / astakos-api-guide.rst @ 2e1e6844
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} |