Statistics
| Branch: | Tag: | Revision:

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

History | View | Annotate | Download (18.1 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
         "user": {
426
             "roles_links": [],
427
             "id": "c18088be-16b1-4263-8180-043c54e22903",
428
             "roles": [{"id": 1, "name": "default"}],
429
             "name": "Firstname Lastname"}}}
430

    
431
Example xml response:
432

    
433
::
434

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

    
437
    <access xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
438
        xmlns="http://docs.openstack.org/identity/api/v2.0">
439
        <token id="CDEe2k0T/HdiJWBMMbHyOA==" expires="2013-06-19T15:23:59.975572+00:00">
440
            <tenant id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname" />
441
        </token>
442
        <user id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname">
443
            <roles>
444
                    <role id="1" name="default"/>
445
            </roles>
446
        </user>
447
        <serviceCatalog>
448
            <service type="account" name="astakos_account">
449
                <endpoint  SNF:uiURL="https://accounts.example.synnefo.org/ui"  versionId="v1.0"  publicURL="https://accounts.example.synnefo.org/account/v1.0"  />
450
            </service>
451
            <service type="identity" name="astakos_identity">
452
                <endpoint  SNF:uiURL="https://accounts.example.synnefo.org/ui"  versionId="v2.0"  publicURL="https://accounts.example.synnefo.org/account/v2.0"  />
453
            </service>
454
            <service type="compute" name="cyclades_compute">
455
                <endpoint  SNF:uiURL="https://cyclades.example.synnefo.org/ui"  versionId="v2.0"  publicURL="https://cyclades.example.synnefo.org/cyclades/compute/v2.0"  />
456
            </service>
457
            <service type="cyclades_vmapi" name="cyclades_vmapi">
458
                <endpoint  SNF:uiURL="https://cyclades.example.synnefo.org/ui"  versionId="v1.0"  publicURL="https://cyclades.example.synnefo.org/cyclades/vmapi/v1.0"  />
459
            </service>
460
            <service type="image" name="cyclades_plankton">
461
                <endpoint  SNF:uiURL="https://cyclades.example.synnefo.org/ui"  versionId="v1.0"  publicURL="https://cyclades.example.synnefo.org/cyclades/image/v1.0"  />
462
            </service>
463
            <service type="public" name="pithos_public">
464
                <endpoint  SNF:uiURL="https://object-store.example.synnefo.org/ui"  versionId="v2.0"  publicURL="https://object-store.example.synnefo.org/pithos/public/v2.0"  />
465
            </service>
466
            <service type="object-store" name="pithos_object-store">
467
                <endpoint  SNF:uiURL="https://object-store.example.synnefo.org/ui"  versionId="v1"  publicURL="https://object-store.example.synnefo.org/pithos/object-store/v1"  /> </service>
468
        </serviceCatalog>
469
    </access>
470

    
471
|
472

    
473
=========================== =====================
474
Return Code                 Description
475
=========================== =====================
476
200 (OK)                    The request succeeded
477
400 (Bad Request)           Method not allowed or invalid request format or missing expected input
478
401 (Unauthorized)          Invalid token or invalid creadentials or tenantName does not comply with the provided token
479
500 (Internal Server Error) The request cannot be completed because of an internal error
480
=========================== =====================