astakos-api-guide.rst 14.7 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 (May 02, 2013)        Change URIs (keep also the old ones until the next version)
24
0.13 (January 21, 2013)    Extend api to export user presentation & quota information.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
25
0.6 (June 06, 2012)        Split service and admin API.
26 27 28
0.1 (Feb 10, 2012)         Initial release.
=========================  ================================

29 30
Get Services
^^^^^^^^^^^^
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
31

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

34 35 36 37 38
============================= =========  ==================
Uri                           Method     Description
============================= =========  ==================
``/astakos/api/get_services`` GET        Get cloud services
============================= =========  ==================
39

40
Example reply:
41

42
::
43

44 45 46 47
    [{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"},
    {"url": "/okeanos.html", "name": "~okeanos", "id": "2"},
    {"url": "/ui/", "name": "pithos+", "id": "3"}]

48 49 50
.. warning:: The service is also available under ``/im/get_services``.
     It  will be removed in the next version.

51 52 53 54 55

Get Menu
^^^^^^^^

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

57 58 59 60 61
========================= =========  ==================
Uri                       Method     Description
========================= =========  ==================
``/astakos/api/get_menu`` GET        Get cloud bar menu
========================= =========  ==================
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 74
    [{"url": "/im/", "name": "user@example.com"},
    {"url": "/im/landing", "name": "Dashboard"},
75
    {"url": "/im/logout", "name": "Sign out"}]
76

77 78 79
.. warning:: The service is also available under ``/im/get_menu``.
     It  will be removed in the next version.

80 81
Admin API Operations
--------------------
82

83
The operations described in this chapter allow users to authenticate themselves, send feedback and get user uuid/displayname mappings.
84

85
All the operations require a valid user token.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
86

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

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

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

94 95 96 97 98
============================= =========  ==================
Uri                           Method     Description
============================= =========  ==================
``/astakos/api/authenticate`` GET        Authenticate user using token
============================= =========  ==================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
99 100 101 102 103 104

|

====================  ===========================
Request Header Name   Value
====================  ===========================
105
X-Auth-Token          User authentication token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
106 107 108 109 110 111 112
====================  ===========================

|

======================  =========================
Request Parameter Name  Value
======================  =========================
113
usage                    (optional)
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
114 115
======================  =========================

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

118 119 120 121 122 123 124 125 126 127 128
===========================  ============================
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
129

130
Example reply without `usage` request parameter:
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
131 132 133

::

134 135 136 137 138 139 140
  {"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
141

142
Example reply with `usage` request parameter:
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
143

144
::
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
145

146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
  {"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",
  "usage": [{"currValue": 4536392,
             "display_name": "Storage Space",
             "description": "Pithos account diskspace",
             "verbose_name": "Storage Space",
             "help_text_input_each": "This is the total amount of space on Pithos that will be granted to each user of this Project ", "maxValue": 5368710653,
             "pluralized_display_name": "Storage Space",
             "report_desc": "Storage Space",
             "help_text": "This is the space on Pithos for storing files and VM Images. ",
             "is_abbreviation": false,
             "placeholder": "eg. 10GB",
             "unit": "bytes",
             "name": "pithos+.diskspace"},
            {"currValue": 0,
             "display_name": "System Disk",
             "description": "Virtual machine disk size",
             "verbose_name": "System Disk",
             "help_text_input_each": "This is the total amount of System Disk that will be granted to each user of this Project (this refers to the total System Disk of all VMs, not each VM's System Disk)  ",
             "maxValue": 53687091200,
             "pluralized_display_name": "System Disk",
             "report_desc": "System Disk",
             "help_text": "This is the System Disk that the VMs have that run the OS ",
             "is_abbreviation": false,
             "placeholder": "eg. 5GB, 2GB etc",
             "unit": "bytes",
             "name": "cyclades.disk"},
            {"currValue": 0,
             "display_name": "CPU",
             "description": "Number of virtual machine processors",
             "verbose_name": "cpu",
             "help_text_input_each": "This is the total number of CPUs that will be granted to each user of this Project (on all VMs)  ", "maxValue": 6, "pluralized_display_name": "CPUs",
             "report_desc": "CPUs",
             "help_text": "CPUs used by VMs ",
             "is_abbreviation": true,
             "placeholder": "eg. 1",
             "unit": "",
             "name": "cyclades.cpu"},
            {"currValue": 0,
             "display_name": "RAM",
             "description": "Virtual machines",
             "verbose_name": "ram",
             "help_text_input_each": "This is the total amount of RAM that will be granted to each user of this Project (on all VMs)  ", "maxValue": 6442450944,
             "pluralized_display_name": "RAM",
             "report_desc": "RAM",
             "help_text": "RAM used by VMs ",
             "is_abbreviation": true,
             "placeholder": "eg. 4GB",
             "unit": "bytes", "name": "cyclades.ram"},
            {"currValue": 0, "display_name": "VM",
             "description": "Number of virtual machines",
             "verbose_name": "vm", "help_text_input_each": "This is the total number of VMs that will be granted to each user of this Project ", "maxValue": 2,
             "pluralized_display_name": "VMs",
             "report_desc": "Virtual Machines",
             "help_text": "These are the VMs one can create on the Cyclades UI ",
             "is_abbreviation": true, "placeholder": "eg. 2",
             "unit": "",
             "name": "cyclades.vm"},
            {"currValue": 0,
             "display_name": "private network",
             "description": "Private networks",
             "verbose_name": "private network",
             "help_text_input_each": "This is the total number of Private Networks that will be granted to each user of this Project ",
             "maxValue": 1,
             "pluralized_display_name": "private networks",
             "report_desc": "Private Networks",
             "help_text": "These are the Private Networks one can create on the Cyclades UI. ",
             "is_abbreviation": false,
             "placeholder": "eg. 1",
             "unit": "",
             "name": "cyclades.network.private"}]}
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
222 223 224 225 226 227 228


|

=========================== =====================
Return Code                 Description
=========================== =====================
229 230 231
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
232 233 234
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================

235 236 237
.. warning:: The service is also available under ``/im/authenticate``.
     It  will be removed in the next version.

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
238 239 240 241

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

242
Post user feedback.
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
243 244 245 246

========================= =========  ==================
Uri                       Method     Description
========================= =========  ==================
247
``astakos/api/feedback``  POST       Send feedback
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
248 249 250 251 252 253 254
========================= =========  ==================

|

====================  ============================
Request Header Name   Value
====================  ============================
255
X-Auth-Token          User authentication token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
256 257
====================  ============================

258 259 260 261 262
|

======================  =========================
Request Parameter Name  Value
======================  =========================
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
263 264
feedback_msg            Feedback message
feedback_data           Additional information about service client status
265 266
======================  =========================

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
267 268 269 270 271 272
|

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

279 280
Get User catalogs
^^^^^^^^^^^^^^^^^
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
281

282
Return a json formatted dictionary containing information about a specific user
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
283 284 285 286

================================ =========  ==================
Uri                              Method     Description
================================ =========  ==================
287
``astakos/api/user_catalogs``    POST       Get 2 catalogs containing uuid to displayname mapping and the opposite
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
288 289 290 291 292 293 294
================================ =========  ==================

|

====================  ============================
Request Header Name   Value
====================  ============================
295
X-Auth-Token          User authentication token
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
296 297 298 299
====================  ============================

|

300
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
301

302
Example request content:
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341

::

  {"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
=========================== =====================

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

342 343 344 345 346
===================================== =========  ==================
Uri                                   Method     Description
===================================== =========  ==================
``astakos/api/service/user_catalogs`` POST       Get 2 catalogs containing uuid to displayname mapping and the opposite
===================================== =========  ==================
347 348 349 350 351 352 353 354 355 356 357 358

|

====================  ============================
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.
359 360
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).
361 362

Example request content:
363 364 365

::

366 367
  {"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
368

369
Example reply:
370

371
::
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
372

373 374 375 376
  {"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"}}
377 378


Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
379
|
380

Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
381 382 383 384
=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    The request succeeded
385
400 (Bad Request)           Method not allowed or request body is not json formatted
Sofia Papagiannaki's avatar
Sofia Papagiannaki committed
386 387 388
401 (Unauthorized)          Missing or expired or invalid service token
500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== =====================