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