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