Statistics
| Branch: | Tag: | Revision:

root / docs / astakos-api-guide.rst @ ddc6960a

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.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 and returns
314
back the token as well as information about the token holder and the services
315
he/she can access.
316

    
317
========================================= =========  ==================
318
Uri                                       Method     Description
319
========================================= =========  ==================
320
``/astakos/api/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
            "passwordCredentials":{
332
                "username":"c18088be-16b1-4263-8180-043c54e22903",
333
                "password":"CDEe2k0T/HdiJWBMMbHyOA=="
334
            },
335
            "tenantName":"c18088be-16b1-4263-8180-043c54e22903"
336
        }
337
    }
338

    
339
or
340

    
341
::
342

    
343
    {
344
        "auth":{
345
            "token":{
346
                "id":"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
    {'serviceCatalog': [
363
        {'endpoints': [{'SNF:uiURL': 'https://node1.example.com/ui/',
364
                        'adminURL': 'https://node1.example.com/v1',
365
                        'internalUrl': 'https://node1.example.com/v1',
366
                        'publicURL': 'https://node1.example.com/v1',
367
                        'region': 'cyclades'}],
368
         'name': 'cyclades',
369
         'type': compute},
370
       {'endpoints': [{'SNF:uiURL': 'https://node2.example.com/ui/',
371
                      'adminURL': 'https://node2.example.com/v1',
372
                      'internalUrl': 'https://node2.example.com/v1',
373
                      'publicURL': 'https://node2.example.com/v1',
374
                      'region': 'pithos'}],
375
        'name': 'pithos',
376
        'type': storage},
377
     'token': {'expires': '2013-06-19T15:23:59.975572+00:00',
378
               'id': 'CDEe2k0T/HdiJWBMMbHyOA==',
379
               'tenant': {'id': 'c18088be-16b1-4263-8180-043c54e22903',
380
                          'name': 'Firstname Lastname'}},
381
     'user': {'id': 'c18088be-16b1-4263-8180-043c54e22903',
382
              'name': 'Firstname Lastname',
383
              'roles': [{'id': 1, 'name': 'default'}],
384
              'roles_links': []}}
385

    
386

    
387
Example xml response:
388

    
389
::
390

    
391
    <?xml version="1.0" encoding="UTF-8"?>
392
    <access xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
393
        xmlns="http://docs.openstack.org/identity/api/v2.0">
394
        <token id="CDEe2k0T/HdiJWBMMbHyOA==" expires="2013-06-19T15:23:59.975572+00:00">
395
            <tenant id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname" />
396
        </token>
397
        <user id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname">
398
            <roles>
399
                    <role id="1" name="default"/>
400
            </roles>
401
        </user>
402
        <serviceCatalog>
403
            <service type="None" name="cyclades">
404
                    <endpoint region="cyclades"
405
                        publicURL="https://node1.example.com/v1"
406
                        adminURL="https://node1.example.com/v1"
407
                        internalURL="https://node1.example.com/v1"
408
                        SNF:uiURL="https://node1.example.com/ui/">
409
                </endpoint>
410
            </service>
411
            <service type="None" name="pithos">
412
                <endpoint
413
                        region="pithos"
414
                        publicURL="https://node2.example.com/v1"
415
                        adminURL="https://node2.example.com/v1"
416
                        internalURL="https://node2.example.com/v1"
417
                        SNF:uiURL="https://node2.example.com/ui/">
418
                </endpoint>
419
            </service>
420
        </serviceCatalog>
421
    </access>
422

    
423
|
424

    
425
=========================== =====================
426
Return Code                 Description
427
=========================== =====================
428
200 (OK)                    The request succeeded
429
400 (Bad Request)           Method not allowed or invalid request format or missing expected input
430
401 (Unauthorized)          Invalid token or invalid creadentials or tenantName does not comply with the provided token
431
500 (Internal Server Error) The request cannot be completed because of an internal error
432
=========================== =====================
433

    
434

    
435

    
436
Get endpoints
437
^^^^^^^^^^^^^
438

    
439
Return a json (or xml) formatted dictionary containing information about registered endpoints
440

    
441
========================================= =========  ==================
442
Uri                                       Method     Description
443
========================================= =========  ==================
444
``/astakos/api/tokens/<token>/endpoints`` GET        Returns a list registered endpoints
445
========================================= =========  ==================
446

    
447
|
448

    
449
====================  ============================
450
Request Header Name   Value
451
====================  ============================
452
X-Auth-Token          User authentication token
453
====================  ============================
454

    
455
|
456

    
457
======================  ============================
458
Request Parameter Name  Value
459

    
460
======================  ============================
461
belongsTo               Check that the token belongs to a supplied user
462
marker                  Return endpoints (ordered by ID) whose ID is higher than the marker
463
limit                   Maximum number of endpoints to return
464
======================  ============================
465

    
466
|
467

    
468
Example json reply:
469

    
470
::
471

    
472
    {"endpoints": [
473
        {"name": "cyclades",
474
         "region": "cyclades",
475
         "internalURL": "https://node1.example.com/v1",
476
         "adminURL": "https://node1.example.com/v1",
477
         "type": null,
478
         "id": 5,
479
         "publicURL": "https://node1.example.com/vi/"},
480
        {"name": "pithos",
481
         "region": "pithos",
482
         "internalURL": "https://node2.example.com/vi/",
483
         "adminURL": "https://node2.example.com/v1",
484
         "type": null,
485
         "id": 6,
486
         "publicURL": "https://node2.example.com/vi/"},
487
    ],
488
    "endpoint_links": [{
489
        "href": "/astakos/api/tokens/0000/endpoints?marker=6&limit=10000",
490
         "rel": "next"}]}
491

    
492

    
493
Example xml reply:
494

    
495
::
496

    
497
    <?xml version="1.0" encoding="UTF-8"?>
498
    <endpoints xmlns="http://docs.openstack.org/identity/api/v2.0">
499
        <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/" />
500
        <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/" />
501
    </endpoints>
502
    <endpoint_links>
503
            <endpoint_link "href"="/astakos/api/tokens/0000/endpoints?marker=6&amp;limit=10000" "rel"="next" />
504
    </endpoint_links>
505

    
506

    
507
|
508

    
509
=========================== =====================
510
Return Code                 Description
511
=========================== =====================
512
200 (OK)                    The request succeeded
513
400 (Bad Request)           Method not allowed or token does not belong to the specific user
514
401 (Unauthorized)          Missing or expired or invalid service token
515
403 (Forbidden)             Path token does not comply with X-Auth-Token
516
500 (Internal Server Error) The request cannot be completed because of an internal error
517
=========================== =====================