root / docs / astakos-api-guide.rst @ 8cb96389
History | View | Annotate | Download (20.1 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.14 (May 28, 2013) Extend token api with authenticate call |
24 |
0.14 (May 23, 2013) Extend api to list endpoints |
25 |
0.14 (May 14, 2013) Do not serve user quotas in :ref:`authenticate-api-label` |
26 |
0.14 (May 02, 2013) Change URIs (keep also the old ones until the next version) |
27 |
0.13 (January 21, 2013) Extend api to export user presentation & quota information. |
28 |
0.6 (June 06, 2012) Split service and user API. |
29 |
0.1 (Feb 10, 2012) Initial release. |
30 |
========================= ================================ |
31 |
|
32 |
Get Services |
33 |
^^^^^^^^^^^^ |
34 |
|
35 |
Returns a json formatted list containing information about the supported cloud services. |
36 |
|
37 |
============================= ========= ================== |
38 |
Uri Method Description |
39 |
============================= ========= ================== |
40 |
``/im/get_services`` GET Get cloud services |
41 |
============================= ========= ================== |
42 |
|
43 |
Example reply: |
44 |
|
45 |
:: |
46 |
|
47 |
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"}, |
48 |
{"url": "/okeanos.html", "name": "~okeanos", "id": "2"}, |
49 |
{"url": "/ui/", "name": "pithos", "id": "3"}] |
50 |
|
51 |
|
52 |
Get Menu |
53 |
^^^^^^^^ |
54 |
|
55 |
Returns a json formatted list containing the cloud bar links. |
56 |
|
57 |
========================= ========= ================== |
58 |
Uri Method Description |
59 |
========================= ========= ================== |
60 |
``/im/get_menu`` GET Get cloud bar menu |
61 |
========================= ========= ================== |
62 |
|
63 |
Example reply if request user is not authenticated: |
64 |
|
65 |
:: |
66 |
|
67 |
[{"url": "/im/", "name": "Sign in"}] |
68 |
|
69 |
Example reply if request user is authenticated: |
70 |
|
71 |
:: |
72 |
|
73 |
[{"url": "/im/", "name": "user@example.com"}, |
74 |
{"url": "/im/landing", "name": "Dashboard"}, |
75 |
{"url": "/im/logout", "name": "Sign out"}] |
76 |
|
77 |
|
78 |
User API Operations |
79 |
-------------------- |
80 |
|
81 |
The operations described in this chapter allow users to authenticate themselves, send feedback and get user uuid/displayname mappings. |
82 |
|
83 |
All the operations require a valid user token. |
84 |
|
85 |
.. _authenticate-api-label: |
86 |
|
87 |
Authenticate |
88 |
^^^^^^^^^^^^ |
89 |
|
90 |
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`) |
91 |
|
92 |
============================= ========= ================== |
93 |
Uri Method Description |
94 |
============================= ========= ================== |
95 |
``/astakos/api/authenticate`` GET Authenticate user using token |
96 |
============================= ========= ================== |
97 |
|
98 |
| |
99 |
|
100 |
==================== =========================== |
101 |
Request Header Name Value |
102 |
==================== =========================== |
103 |
X-Auth-Token User authentication token |
104 |
==================== =========================== |
105 |
|
106 |
Extended information on the user serialized in the json format will be returned: |
107 |
|
108 |
=========================== ============================ |
109 |
Name Description |
110 |
=========================== ============================ |
111 |
displayname User displayname |
112 |
uuid User unique identifier |
113 |
email List with user emails |
114 |
name User full name |
115 |
auth_token_created Token creation date |
116 |
auth_token_expires Token expiration date |
117 |
usage List of user resource usage (if usage request parameter is present) |
118 |
=========================== ============================ |
119 |
|
120 |
Example reply: |
121 |
|
122 |
:: |
123 |
|
124 |
{"id": "12", |
125 |
"displayname": "user@example.com", |
126 |
"uuid": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
127 |
"email": "[user@example.com]", |
128 |
"name": "Firstname Lastname", |
129 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT", |
130 |
"auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT"} |
131 |
|
132 |
| |
133 |
|
134 |
=========================== ===================== |
135 |
Return Code Description |
136 |
=========================== ===================== |
137 |
204 (No Content) The request succeeded |
138 |
400 (Bad Request) Method not allowed or no user found |
139 |
401 (Unauthorized) Missing token or inactive user or penging approval terms |
140 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
141 |
=========================== ===================== |
142 |
|
143 |
.. warning:: The service is also available under ``/im/authenticate``. |
144 |
It will be removed in the next version. |
145 |
|
146 |
|
147 |
Send feedback |
148 |
^^^^^^^^^^^^^ |
149 |
|
150 |
Post user feedback. |
151 |
|
152 |
========================= ========= ================== |
153 |
Uri Method Description |
154 |
========================= ========= ================== |
155 |
``/astakos/api/feedback`` POST Send feedback |
156 |
========================= ========= ================== |
157 |
|
158 |
| |
159 |
|
160 |
==================== ============================ |
161 |
Request Header Name Value |
162 |
==================== ============================ |
163 |
X-Auth-Token User authentication token |
164 |
==================== ============================ |
165 |
|
166 |
| |
167 |
|
168 |
====================== ========================= |
169 |
Request Parameter Name Value |
170 |
====================== ========================= |
171 |
feedback_msg Feedback message |
172 |
feedback_data Additional information about service client status |
173 |
====================== ========================= |
174 |
|
175 |
| |
176 |
|
177 |
=========================== ===================== |
178 |
Return Code Description |
179 |
=========================== ===================== |
180 |
200 (OK) The request succeeded |
181 |
502 (Bad Gateway) Send feedback failure |
182 |
400 (Bad Request) Method not allowed or invalid message data |
183 |
401 (Unauthorized) Missing or expired user token |
184 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
185 |
=========================== ===================== |
186 |
|
187 |
.. warning:: The service is also available under ``/feedback``. |
188 |
It will be removed in the next version. |
189 |
|
190 |
Get User catalogs |
191 |
^^^^^^^^^^^^^^^^^ |
192 |
|
193 |
Return a json formatted dictionary containing information about a specific user |
194 |
|
195 |
================================ ========= ================== |
196 |
Uri Method Description |
197 |
================================ ========= ================== |
198 |
``/astakos/api/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
199 |
================================ ========= ================== |
200 |
|
201 |
| |
202 |
|
203 |
==================== ============================ |
204 |
Request Header Name Value |
205 |
==================== ============================ |
206 |
X-Auth-Token User authentication token |
207 |
==================== ============================ |
208 |
|
209 |
| |
210 |
|
211 |
The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
212 |
|
213 |
Example request content: |
214 |
|
215 |
:: |
216 |
|
217 |
{"displaynames": ["user1@example.com", "user2@example.com"], |
218 |
"uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
219 |
|
220 |
Example reply: |
221 |
|
222 |
:: |
223 |
|
224 |
{"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
225 |
"user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
226 |
'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
227 |
"ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
228 |
|
229 |
|
230 |
| |
231 |
|
232 |
=========================== ===================== |
233 |
Return Code Description |
234 |
=========================== ===================== |
235 |
200 (OK) The request succeeded |
236 |
400 (Bad Request) Method not allowed or request body is not json formatted |
237 |
401 (Unauthorized) Missing or expired or invalid user token |
238 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
239 |
=========================== ===================== |
240 |
|
241 |
.. warning:: The service is also available under ``/user_catalogs``. |
242 |
It will be removed in the next version. |
243 |
|
244 |
Service API Operations |
245 |
---------------------- |
246 |
|
247 |
The operations described in this chapter allow services to get user uuid/displayname mappings. |
248 |
|
249 |
All the operations require a valid service token. |
250 |
|
251 |
Get User catalogs |
252 |
^^^^^^^^^^^^^^^^^ |
253 |
|
254 |
Return a json formatted dictionary containing information about a specific user |
255 |
|
256 |
====================================== ========= ================== |
257 |
Uri Method Description |
258 |
====================================== ========= ================== |
259 |
``/astakos/api/service/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
260 |
====================================== ========= ================== |
261 |
|
262 |
| |
263 |
|
264 |
==================== ============================ |
265 |
Request Header Name Value |
266 |
==================== ============================ |
267 |
X-Auth-Token Service authentication token |
268 |
==================== ============================ |
269 |
|
270 |
| |
271 |
|
272 |
The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
273 |
If instead of list null is passed then the response contains the information for all the system users (For discretion purposes |
274 |
this behavior is **not** exposed in the respective call of the User API). |
275 |
|
276 |
Example request content: |
277 |
|
278 |
:: |
279 |
|
280 |
{"displaynames": ["user1@example.com", "user2@example.com"], |
281 |
"uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
282 |
|
283 |
Example reply: |
284 |
|
285 |
:: |
286 |
|
287 |
{"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
288 |
"user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
289 |
'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
290 |
"ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
291 |
|
292 |
|
293 |
| |
294 |
|
295 |
=========================== ===================== |
296 |
Return Code Description |
297 |
=========================== ===================== |
298 |
200 (OK) The request succeeded |
299 |
400 (Bad Request) Method not allowed or request body is not json formatted |
300 |
401 (Unauthorized) Missing or expired or invalid service token |
301 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
302 |
=========================== ===================== |
303 |
|
304 |
.. warning:: The service is also available under ``/service/api/user_catalogs``. |
305 |
It will be removed in the next version. |
306 |
|
307 |
Tokens API Operations |
308 |
---------------------- |
309 |
|
310 |
Authenticate |
311 |
^^^^^^^^^^^^ |
312 |
|
313 |
Fallback call which receives the user token or the user uuid/token pair and |
314 |
returns back the token as well as information about the token holder and the |
315 |
services he/she can access. |
316 |
|
317 |
========================================= ========= ================== |
318 |
Uri Method Description |
319 |
========================================= ========= ================== |
320 |
``/identity/v2.0/tokens/`` POST Checks whether the provided token is valid and conforms with the provided uuid (if present) and returns back information about the user |
321 |
========================================= ========= ================== |
322 |
|
323 |
The input should be json formatted. |
324 |
|
325 |
Example request: |
326 |
|
327 |
:: |
328 |
|
329 |
{ |
330 |
"auth":{ |
331 |
"token":{ |
332 |
"id":"CDEe2k0T/HdiJWBMMbHyOA==" |
333 |
}, |
334 |
"tenantName":"c18088be-16b1-4263-8180-043c54e22903" |
335 |
} |
336 |
} |
337 |
|
338 |
or |
339 |
|
340 |
:: |
341 |
|
342 |
{ |
343 |
"auth":{ |
344 |
"passwordCredentials":{ |
345 |
"username":"c18088be-16b1-4263-8180-043c54e22903", |
346 |
"password":"CDEe2k0T/HdiJWBMMbHyOA==" |
347 |
}, |
348 |
"tenantName":"c18088be-16b1-4263-8180-043c54e22903" |
349 |
} |
350 |
} |
351 |
|
352 |
|
353 |
The tenantName in the above requests is optional. |
354 |
|
355 |
The response is json formatted unless it is requested otherwise via format |
356 |
request parameter or Accept header. |
357 |
|
358 |
Example json response: |
359 |
|
360 |
:: |
361 |
|
362 |
{"access": { |
363 |
"serviceCatalog": [ |
364 |
{"SNF:uiURL": "https://node2.example.com/ui/", |
365 |
"endpoints": [{ |
366 |
"publicURL": "https://object-store.example.synnefo.org/pithos/public/v2.0", |
367 |
"versionId": "v2.0"}], |
368 |
"endpoints_links": [], |
369 |
"name": "pithos_public", |
370 |
"type": "public"}, |
371 |
{"SNF:uiURL": "https://node2.example.com/ui/", |
372 |
"endpoints": [{ |
373 |
"publicURL": "https://object-store.example.synnefo.org/pithos/object-store/v1", |
374 |
"versionId": "v1"}], |
375 |
"endpoints_links": [], |
376 |
"name": "pithos_object-store", |
377 |
"type": "object-store"}, |
378 |
{"SNF:uiURL": "https://node2.example.com/ui/", |
379 |
"endpoints": [{ |
380 |
"publicURL": "https://object-store.example.synnefo.org/pithos/ui", |
381 |
"versionId": ""}], |
382 |
"endpoints_links": [], |
383 |
"name": "pithos_ui", |
384 |
"type": "pithos_ui"}, |
385 |
{"SNF:uiURL": "http://localhost:8080", |
386 |
"endpoints": [{ |
387 |
"publicURL": "https://accounts.example.synnefo.org/ui/v1.0", |
388 |
"versionId": "v1.0"}], |
389 |
"endpoints_links": [], |
390 |
"name": "astakos_ui", |
391 |
"type": "astakos_ui"}, |
392 |
{"SNF:uiURL": "http://localhost:8080", |
393 |
"endpoints": [{ |
394 |
"publicURL": "https://accounts.example.synnefo.org/account/v1.0", |
395 |
"versionId": "v1.0"}], |
396 |
"endpoints_links": [], |
397 |
"name": "astakos_account", |
398 |
"type": "account"}, |
399 |
{"SNF:uiURL": "http://localhost:8080", |
400 |
"endpoints": [{ |
401 |
"publicURL": "https://accounts.example.synnefo.org/identity/v2.0", |
402 |
"versionId": "v2.0"}], |
403 |
"endpoints_links": [], |
404 |
"name": "astakos_keystone", |
405 |
"type": "identity"}], |
406 |
"token": { |
407 |
"expires": "2013-06-19T15:23:59.975572+00:00", |
408 |
"id": "CDEe2k0T/HdiJWBMMbHyOA==", |
409 |
"tenant": {"id": "c18088be-16b1-4263-8180-043c54e22903", |
410 |
"name": "Firstname Lastname"}}, |
411 |
"user": { |
412 |
"id": "c18088be-16b1-4263-8180-043c54e22903", |
413 |
"name": "Firstname Lastname", |
414 |
"roles": [{"id": 1, "name": "default"}, |
415 |
"roles_links": []}}} |
416 |
|
417 |
Example xml response: |
418 |
|
419 |
:: |
420 |
|
421 |
<?xml version="1.0" encoding="UTF-8"?> |
422 |
|
423 |
<access xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
424 |
xmlns="http://docs.openstack.org/identity/api/v2.0"> |
425 |
<token id="CDEe2k0T/HdiJWBMMbHyOA==" expires="2013-06-19T15:23:59.975572+00:00"> |
426 |
<tenant id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname" /> |
427 |
</token> |
428 |
<user id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname"> |
429 |
<roles> |
430 |
<role id="1" name="default"/> |
431 |
</roles> |
432 |
</user> |
433 |
<serviceCatalog> |
434 |
<service type="public" name="pithos_public" SNF:uiURL=""> |
435 |
<endpoint |
436 |
versionId="v2.0" |
437 |
publicURL="https://object-store.example.synnefo.org/pithos/public/v2.0" |
438 |
</service> |
439 |
<service type="object-store" name="pithos_object-store" SNF:uiURL=""> |
440 |
<endpoint |
441 |
versionId="v1" |
442 |
publicURL="https://object-store.example.synnefo.org/pithos/object-store/v1" |
443 |
</service> |
444 |
<service type="pithos_ui" name="pithos_ui" SNF:uiURL=""> |
445 |
<endpoint |
446 |
versionId="" |
447 |
publicURL="https://object-store.example.synnefo.org/pithos/ui" |
448 |
</service> |
449 |
<service type="astakos_ui" name="astakos_ui" SNF:uiURL=""> |
450 |
<endpoint |
451 |
versionId="v1.0" |
452 |
publicURL="https://accounts.example.synnefo.org/ui/v1.0" |
453 |
</service> |
454 |
<service type="account" name="astakos_account" SNF:uiURL=""> |
455 |
<endpoint |
456 |
versionId="v1.0" |
457 |
publicURL="https://accounts.example.synnefo.org/account/v1.0" |
458 |
</service> |
459 |
<service type="identity" name="astakos_keystone" SNF:uiURL=""> |
460 |
<endpoint |
461 |
versionId="v2.0" |
462 |
publicURL="https://accounts.example.synnefo.org/identity/v2.0" |
463 |
</service> |
464 |
</serviceCatalog> |
465 |
</access> |
466 |
|
467 |
| |
468 |
|
469 |
=========================== ===================== |
470 |
Return Code Description |
471 |
=========================== ===================== |
472 |
200 (OK) The request succeeded |
473 |
400 (Bad Request) Method not allowed or invalid request format or missing expected input |
474 |
401 (Unauthorized) Invalid token or invalid creadentials or tenantName does not comply with the provided token |
475 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
476 |
=========================== ===================== |
477 |
|
478 |
|
479 |
|
480 |
Get endpoints |
481 |
^^^^^^^^^^^^^ |
482 |
|
483 |
Return a json (or xml) formatted dictionary containing information about registered endpoints |
484 |
|
485 |
========================================= ========= ================== |
486 |
Uri Method Description |
487 |
========================================= ========= ================== |
488 |
``/astakos/api/tokens/<token>/endpoints`` GET Returns a list registered endpoints |
489 |
========================================= ========= ================== |
490 |
|
491 |
| |
492 |
|
493 |
==================== ============================ |
494 |
Request Header Name Value |
495 |
==================== ============================ |
496 |
X-Auth-Token User authentication token |
497 |
==================== ============================ |
498 |
|
499 |
| |
500 |
|
501 |
====================== ============================ |
502 |
Request Parameter Name Value |
503 |
|
504 |
====================== ============================ |
505 |
belongsTo Check that the token belongs to a supplied user |
506 |
marker Return endpoints (ordered by ID) whose ID is higher than the marker |
507 |
limit Maximum number of endpoints to return |
508 |
====================== ============================ |
509 |
|
510 |
| |
511 |
|
512 |
Example json reply: |
513 |
|
514 |
:: |
515 |
|
516 |
{"endpoints": [ |
517 |
{"name": "cyclades", |
518 |
"region": "cyclades", |
519 |
"internalURL": "https://node1.example.com/v1", |
520 |
"adminURL": "https://node1.example.com/v1", |
521 |
"type": null, |
522 |
"id": 5, |
523 |
"publicURL": "https://node1.example.com/vi/"}, |
524 |
{"name": "pithos", |
525 |
"region": "pithos", |
526 |
"internalURL": "https://node2.example.com/vi/", |
527 |
"adminURL": "https://node2.example.com/v1", |
528 |
"type": null, |
529 |
"id": 6, |
530 |
"publicURL": "https://node2.example.com/vi/"}, |
531 |
], |
532 |
"endpoint_links": [{ |
533 |
"href": "/astakos/api/tokens/0000/endpoints?marker=6&limit=10000", |
534 |
"rel": "next"}]} |
535 |
|
536 |
|
537 |
Example xml reply: |
538 |
|
539 |
:: |
540 |
|
541 |
<?xml version="1.0" encoding="UTF-8"?> |
542 |
<endpoints xmlns="http://docs.openstack.org/identity/api/v2.0"> |
543 |
<endpoint "name"="cyclades" "region"="cyclades" "internalURL"="https://node1.example.com/ui/" "adminURL"="https://node1.example.com/ui/" "id"="5" "publicURL"="https://node1.example.com/ui/" /> |
544 |
<endpoint "name"="pithos" "region"="pithos" "internalURL"="https://node2.example.com/ui/" "adminURL"="https://node2.example.com/v1" "id"="6" "publicURL"="https://node2.example.com/ui/" /> |
545 |
</endpoints> |
546 |
<endpoint_links> |
547 |
<endpoint_link "href"="/astakos/api/tokens/0000/endpoints?marker=6&limit=10000" "rel"="next" /> |
548 |
</endpoint_links> |
549 |
|
550 |
|
551 |
| |
552 |
|
553 |
=========================== ===================== |
554 |
Return Code Description |
555 |
=========================== ===================== |
556 |
200 (OK) The request succeeded |
557 |
400 (Bad Request) Method not allowed or token does not belong to the specific user |
558 |
401 (Unauthorized) Missing or expired or invalid service token |
559 |
403 (Forbidden) Path token does not comply with X-Auth-Token |
560 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
561 |
=========================== ===================== |