astakos-api-guide.rst 18.8 KB
Newer Older
1
Astakos API
2 3 4 5 6 7 8 9
===========

This is Astakos API guide.

Overview
--------


10 11 12
Astakos service co-ordinates the access to resources (and the subsequent
permission model) and acts as the single point of registry and entry to the
GRNET cloud services.
13 14 15 16 17 18 19 20 21 22

This document's goals is to describe the APIs to the outer world.
Make sure you have read the :ref:`astakos` general architecture first.

Document Revisions
^^^^^^^^^^^^^^^^^^

=========================  ================================
Revision                   Description
=========================  ================================
23
0.14 (June 03, 2013)       Remove endpoint listing
24
0.14 (May 28, 2013)        Extend token api with authenticate call
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
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 31 32
0.1 (Feb 10, 2012)         Initial release.
=========================  ================================

33 34
Get Services
^^^^^^^^^^^^
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
35

36
Returns a json formatted list containing information about the supported cloud services.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
37

38 39 40
============================= =========  ==================
Uri                           Method     Description
============================= =========  ==================
41
``/ui/get_services``          GET        Get cloud services
42
============================= =========  ==================
43

44
Example reply:
45

46
::
47

48 49
    [{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"},
    {"url": "/okeanos.html", "name": "~okeanos", "id": "2"},
50
    {"url": "/ui/", "name": "pithos", "id": "3"}]
51 52 53 54 55 56


Get Menu
^^^^^^^^

Returns a json formatted list containing the cloud bar links.
57

58 59 60
========================= =========  ==================
Uri                       Method     Description
========================= =========  ==================
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 75 76
    [{"url": "/ui/", "name": "user@example.com"},
    {"url": "/ui/landing", "name": "Dashboard"},
    {"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.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
85

86 87 88 89
.. _authenticate-api-label:

Authenticate
^^^^^^^^^^^^
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
90

91 92
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`)

93 94 95 96 97
============================== =========  ==================
Uri                            Method     Description
============================== =========  ==================
``/account/v1.0/authenticate`` GET        Authenticate user using token
============================== =========  ==================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
98 99 100 101 102 103

|

====================  ===========================
Request Header Name   Value
====================  ===========================
104
X-Auth-Token          User authentication token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
105 106
====================  ===========================

107
Extended information on the user serialized in the json format will be returned:
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
108

109 110 111 112 113 114 115 116 117 118 119
===========================  ============================
Name                         Description
===========================  ============================
displayname                     User displayname
uuid                         User unique identifier
email                        List with user emails
name                         User full name
auth_token_created           Token creation date
auth_token_expires           Token expiration date
usage                        List of user resource usage (if usage request parameter is present)
===========================  ============================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
120

121
Example reply:
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
122 123 124

::

125 126 127 128 129 130 131
  {"id": "12",
  "displayname": "user@example.com",
  "uuid": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8",
  "email": "[user@example.com]",
  "name": "Firstname Lastname",
  "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
  "auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT"}
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
132 133 134 135 136 137

|

=========================== =====================
Return Code                 Description
=========================== =====================
138 139 140
204 (No Content)            The request succeeded
400 (Bad Request)           Method not allowed or no user found
401 (Unauthorized)          Missing token or inactive user or penging approval terms
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
141 142 143
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================

144
.. warning:: The service is also available under ``/ui/authenticate``.
145 146
     It  will be removed in the next version.

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
147 148 149 150

Send feedback
^^^^^^^^^^^^^

151
Post user feedback.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
152

153 154 155 156 157
========================== =========  ==================
Uri                        Method     Description
========================== =========  ==================
``/account/v1.0/feedback`` POST       Send feedback
========================== =========  ==================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
158 159 160 161 162 163

|

====================  ============================
Request Header Name   Value
====================  ============================
164
X-Auth-Token          User authentication token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
165 166
====================  ============================

167 168 169 170 171
|

======================  =========================
Request Parameter Name  Value
======================  =========================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
172 173
feedback_msg            Feedback message
feedback_data           Additional information about service client status
174 175
======================  =========================

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
176 177 178 179 180 181
|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    The request succeeded
182
502 (Bad Gateway)           Send feedback failure
183 184
400 (Bad Request)           Method not allowed or invalid message data
401 (Unauthorized)          Missing or expired user token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
185 186 187
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================

188 189 190
.. warning:: The service is also available under ``/feedback``.
     It  will be removed in the next version.

191 192
Get User catalogs
^^^^^^^^^^^^^^^^^
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
193

194
Return a json formatted dictionary containing information about a specific user
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
195

196 197 198 199 200
=============================== =========  ==================
Uri                             Method     Description
=============================== =========  ==================
``/account/v1.0/user_catalogs`` POST       Get 2 catalogs containing uuid to displayname mapping and the opposite
=============================== =========  ==================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
201 202 203 204 205 206

|

====================  ============================
Request Header Name   Value
====================  ============================
207
X-Auth-Token          User authentication token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
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.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
213

214
Example request content:
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241

::

  {"displaynames": ["user1@example.com", "user2@example.com"],
   "uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]}

Example reply:

::

  {"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8",
                           "user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"},
  'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com",
                   "ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}}


|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    The request succeeded
400 (Bad Request)           Method not allowed or request body is not json formatted
401 (Unauthorized)          Missing or expired or invalid user token
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================

242 243 244
.. warning:: The service is also available under ``/user_catalogs``.
     It  will be removed in the next version.

245 246 247 248 249 250 251 252 253 254 255 256
Service API Operations
----------------------

The operations described in this chapter allow services to get user uuid/displayname mappings.

All the operations require a valid service token.

Get User catalogs
^^^^^^^^^^^^^^^^^

Return a json formatted dictionary containing information about a specific user

257 258 259 260 261
======================================= =========  ==================
Uri                                     Method     Description
======================================= =========  ==================
``/account/v1.0/service/user_catalogs`` POST       Get 2 catalogs containing uuid to displayname mapping and the opposite
======================================= =========  ==================
262 263 264 265 266 267 268 269 270 271 272 273

|

====================  ============================
Request Header Name   Value
====================  ============================
X-Auth-Token          Service authentication token
====================  ============================

|

The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate.
274 275
If instead of list null is passed then the response contains the information for all the system users (For discretion purposes
this behavior is **not** exposed in the respective call of the User API).
276 277

Example request content:
278 279 280

::

281 282
  {"displaynames": ["user1@example.com", "user2@example.com"],
   "uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]}
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
283

284
Example reply:
285

286
::
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
287

288 289 290 291
  {"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8",
                           "user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"},
  'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com",
                   "ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}}
292 293


Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
294
|
295

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
296 297 298 299
=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    The request succeeded
300
400 (Bad Request)           Method not allowed or request body is not json formatted
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
301 302 303
401 (Unauthorized)          Missing or expired or invalid service token
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================
304 305 306

.. warning:: The service is also available under ``/service/api/user_catalogs``.
     It  will be removed in the next version.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
307 308 309 310

Tokens API Operations
----------------------

311 312 313
Authenticate
^^^^^^^^^^^^

314 315 316
Fallback call which receives the user token or the user uuid/token pair and
returns back the token as well as information about the token holder and the
services he/she can access.
317 318 319
If not request body is provided (the request content length is missing or
equals to 0) the response contains only non authentication protected
information (the service catalog).
320 321 322 323

========================================= =========  ==================
Uri                                       Method     Description
========================================= =========  ==================
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 328 329 330 331 332 333 334
========================================= =========  ==================

The input should be json formatted.

Example request:

::

    {
        "auth":{
335
            "token":{
336
                "id":"CDEe2k0T/HdiJWBMMbHyOA"
337 338 339 340 341 342 343 344 345 346 347
            },
            "tenantName":"c18088be-16b1-4263-8180-043c54e22903"
        }
    }

or

::

    {
        "auth":{
348 349
            "passwordCredentials":{
                "username":"c18088be-16b1-4263-8180-043c54e22903",
350
                "password":"CDEe2k0T/HdiJWBMMbHyOA"
351 352 353 354 355 356
            },
            "tenantName":"c18088be-16b1-4263-8180-043c54e22903"
        }
    }


357 358
The tenantName in the above requests is optional.

359 360 361 362 363 364 365
The response is json formatted unless it is requested otherwise via format
request parameter or Accept header.

Example json response:

::

366
    {"access": {
367 368 369 370 371 372 373 374
        "token": {
            "expires": "2013-06-19T15:23:59.975572+00:00",
            "id": "CDEe2k0T/HdiJWBMMbHyOA==",
            "tenant": {
                "id": "c18088be-16b1-4263-8180-043c54e22903",
                "name": "Firstname Lastname"
            }
        },
375
        "serviceCatalog": [
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423
            {"endpoints_links": [],
             "endpoints": [{
                "SNF:uiURL": "https://accounts.example.synnefo.org/ui",
                "versionId": "v1.0",
                "publicURL": "https://accounts.example.synnefo.org/account/v1.0"}],
             "type": "account",
             "name": "astakos_account"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://accounts.example.synnefo.org/ui",
                 "versionId": "v2.0",
                 "publicURL": "https://accounts.example.synnefo.org/account/v2.0"}],
             "type": "identity",
             "name": "astakos_identity"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://cyclades.example.synnefo.org/ui",
                 "versionId": "v2.0",
                 "publicURL": "https://cyclades.example.synnefo.org/cyclades/compute/v2.0"}],
             "type": "compute",
             "name": "cyclades_compute"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://cyclades.example.synnefo.org/ui",
                 "versionId": "v1.0",
                 "publicURL": "https://cyclades.example.synnefo.org/cyclades/vmapi/v1.0"}],
             "type": "cyclades_vmapi",
             "name": "cyclades_vmapi"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://cyclades.example.synnefo.org/ui",
                 "versionId": "v1.0",
                 "publicURL": "https://cyclades.example.synnefo.org/cyclades/image/v1.0"}],
             "type": "image",
             "name": "cyclades_plankton"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://object-store.example.synnefo.org/ui",
                 "versionId": "v2.0",
                 "publicURL": "https://object-store.example.synnefo.org/pithos/public/v2.0"}],
             "type": "public",
             "name": "pithos_public"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://object-store.example.synnefo.org/ui",
                 "versionId": "v1",
                 "publicURL": "https://object-store.example.synnefo.org/pithos/object-store/v1"}],
             "type": "object-store",
424 425 426 427 428
             "name": "pithos_object-store"},
            {"endpoints_links": [],
             "endpoints": [{
                 "SNF:uiURL": "https://accounts.example.synnefo.org/ui",
                 "versionId": "",
429
                 "SNF:webloginURL": "http://localhost:8080/astakos/weblogin"
430 431 432
                 "publicURL": "https://accounts.example.synnefo.org/astakos/weblogin"}],
             "type": "astakos_weblogin",
             "name": "astakos_weblogin"}],
433 434 435 436 437
         "user": {
             "roles_links": [],
             "id": "c18088be-16b1-4263-8180-043c54e22903",
             "roles": [{"id": 1, "name": "default"}],
             "name": "Firstname Lastname"}}}
438 439 440 441 442 443

Example xml response:

::

    <?xml version="1.0" encoding="UTF-8"?>
444

445 446
    <access xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://docs.openstack.org/identity/api/v2.0">
447
        <token id="CDEe2k0T/HdiJWBMMbHyOA==" expires="2013-06-19T15:23:59.975572+00:00">
448 449 450 451 452 453 454 455
            <tenant id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname" />
        </token>
        <user id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname">
            <roles>
                    <role id="1" name="default"/>
            </roles>
        </user>
        <serviceCatalog>
456 457
            <service type="account" name="astakos_account">
                <endpoint  SNF:uiURL="https://accounts.example.synnefo.org/ui"  versionId="v1.0"  publicURL="https://accounts.example.synnefo.org/account/v1.0"  />
458
            </service>
459 460
            <service type="identity" name="astakos_identity">
                <endpoint  SNF:uiURL="https://accounts.example.synnefo.org/ui"  versionId="v2.0"  publicURL="https://accounts.example.synnefo.org/account/v2.0"  />
461
            </service>
462 463
            <service type="compute" name="cyclades_compute">
                <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 466
            <service type="cyclades_vmapi" name="cyclades_vmapi">
                <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 469
            <service type="image" name="cyclades_plankton">
                <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 472
            <service type="public" name="pithos_public">
                <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 475
            <service type="object-store" name="pithos_object-store">
                <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 479 480 481 482 483 484 485 486
        </serviceCatalog>
    </access>

|

=========================== =====================
Return Code                 Description
=========================== =====================
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 489 490
401 (Unauthorized)          Invalid token or invalid creadentials or tenantName does not comply with the provided token
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================