Revision 949f8393 docs/astakos-api-guide.rst
| b/docs/astakos-api-guide.rst | ||
|---|---|---|
| 20 | 20 |
========================= ================================ |
| 21 | 21 |
Revision Description |
| 22 | 22 |
========================= ================================ |
| 23 |
0.6 (June 06, 2012) Split service and admin API. |
|
| 23 | 24 |
0.1 (Feb 10, 2012) Initial release. |
| 24 | 25 |
========================= ================================ |
| 25 | 26 |
|
| 26 |
API Operations |
|
| 27 |
-------------- |
|
| 27 |
Admin API Operations |
|
| 28 |
-------------------- |
|
| 29 |
|
|
| 30 |
The operations described in this chapter allow users to authenticate themselves and priviledged users (ex. helpdesk) to access other user information. |
|
| 31 |
|
|
| 32 |
Most of the operations require a valid token assigned to users having the necessary permissions. |
|
| 28 | 33 |
|
| 29 | 34 |
.. _authenticate-api-label: |
| 30 | 35 |
|
| ... | ... | |
| 59 | 64 |
auth_token_created Token creation date |
| 60 | 65 |
has_credits Whether user has credits |
| 61 | 66 |
has_signed_terms Whether user has aggred on terms |
| 67 |
groups User groups |
|
| 62 | 68 |
=========================== ============================ |
| 63 | 69 |
|
| 64 | 70 |
Example reply: |
| ... | ... | |
| 66 | 72 |
:: |
| 67 | 73 |
|
| 68 | 74 |
{"username": "4ad9f34d6e7a4992b34502d40f40cb",
|
| 69 |
"uniq": "papagian@example.com"
|
|
| 75 |
"uniq": "user@example.com"
|
|
| 70 | 76 |
"auth_token": "0000", |
| 71 |
"auth_token_expires": "Tue, 11-Sep-2012 09:17:14 ",
|
|
| 72 |
"auth_token_created": "Sun, 11-Sep-2011 09:17:14 ",
|
|
| 77 |
"auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT",
|
|
| 78 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
|
|
| 73 | 79 |
"has_credits": false, |
| 74 | 80 |
"has_signed_terms": true} |
| 75 | 81 |
|
| ... | ... | |
| 79 | 85 |
Return Code Description |
| 80 | 86 |
=========================== ===================== |
| 81 | 87 |
204 (No Content) The request succeeded |
| 82 |
400 (Bad Request) The request is invalid
|
|
| 88 |
400 (Bad Request) Method not allowed or no user found
|
|
| 83 | 89 |
401 (Unauthorized) Missing token or inactive user or penging approval terms |
| 84 | 90 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
| 85 | 91 |
=========================== ===================== |
| 86 | 92 |
|
| 93 |
Get User by email |
|
| 94 |
^^^^^^^^^^^^^^^^^ |
|
| 95 |
|
|
| 96 |
Returns a json formatted dictionary containing information about a specific user |
|
| 97 |
|
|
| 98 |
============================== ========= ================== |
|
| 99 |
Uri Method Description |
|
| 100 |
============================== ========= ================== |
|
| 101 |
``/im/admin/api/v2.0/users/`` GET Get user information by email |
|
| 102 |
============================== ========= ================== |
|
| 103 |
|
|
| 104 |
| |
|
| 105 |
|
|
| 106 |
==================== =========================== |
|
| 107 |
Request Header Name Value |
|
| 108 |
==================== =========================== |
|
| 109 |
X-Auth-Token Authentication token owned by |
|
| 110 |
a user has or inherits ``im.can_access_userinfo`` permission |
|
| 111 |
==================== =========================== |
|
| 112 |
|
|
| 113 |
| |
|
| 114 |
|
|
| 115 |
====================== ========================= |
|
| 116 |
Request Parameter Name Value |
|
| 117 |
====================== ========================= |
|
| 118 |
name Email |
|
| 119 |
====================== ========================= |
|
| 120 |
|
|
| 121 |
|
|
| 122 |
| |
|
| 123 |
|
|
| 124 |
=========================== ===================== |
|
| 125 |
Return Code Description |
|
| 126 |
=========================== ===================== |
|
| 127 |
200 (OK) The request succeeded |
|
| 128 |
400 (Bad Request) Method not allowed |
|
| 129 |
401 (Unauthorized) Missing or invalid token or unauthorized user |
|
| 130 |
404 (Not Found) Missing email or inactive user |
|
| 131 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
| 132 |
=========================== ===================== |
|
| 133 |
|
|
| 134 |
Example reply: |
|
| 135 |
|
|
| 136 |
:: |
|
| 137 |
|
|
| 138 |
{"username": "7e530044f90a4e7ba2cb94f3a26c40",
|
|
| 139 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT", |
|
| 140 |
"name": "Firstname Surname", |
|
| 141 |
"groups": ["default"], |
|
| 142 |
"user_permissions": [], |
|
| 143 |
"has_credits": false, |
|
| 144 |
"auth_token_expires":"Fri, 29 Jun 2012 10:03:37 GMT", |
|
| 145 |
"enabled": true, |
|
| 146 |
"email": ["user@example.com"], |
|
| 147 |
"id": 4} |
|
| 148 |
|
|
| 149 |
Get User by username |
|
| 150 |
^^^^^^^^^^^^^^^^^^^^ |
|
| 151 |
|
|
| 152 |
Returns a json formatted dictionary containing information about a specific user |
|
| 153 |
|
|
| 154 |
======================================== ========= ================== |
|
| 155 |
Uri Method Description |
|
| 156 |
======================================== ========= ================== |
|
| 157 |
``/im/admin/api/v2.0/users/{username}`` GET Get user information by username
|
|
| 158 |
======================================== ========= ================== |
|
| 159 |
|
|
| 160 |
| |
|
| 161 |
|
|
| 162 |
==================== =========================== |
|
| 163 |
Request Header Name Value |
|
| 164 |
==================== =========================== |
|
| 165 |
X-Auth-Token Authentication token owned |
|
| 166 |
by a user has or inherits ``im.can_access_userinfo`` permission |
|
| 167 |
==================== =========================== |
|
| 168 |
|
|
| 169 |
| |
|
| 170 |
|
|
| 171 |
=========================== ===================== |
|
| 172 |
Return Code Description |
|
| 173 |
=========================== ===================== |
|
| 174 |
200 (OK) The request succeeded |
|
| 175 |
400 (Bad Request) Method not allowed |
|
| 176 |
401 (Unauthorized) Missing or invalid token or unauthorized user |
|
| 177 |
404 (Not Found) Invalid username |
|
| 178 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
| 179 |
=========================== ===================== |
|
| 180 |
|
|
| 181 |
Example reply: |
|
| 182 |
|
|
| 183 |
:: |
|
| 184 |
|
|
| 185 |
{"username": "7e530044f90a4e7ba2cb94f3a26c40",
|
|
| 186 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT", |
|
| 187 |
"name": "Firstname Surname", |
|
| 188 |
"groups": ["default"], |
|
| 189 |
"user_permissions": [], |
|
| 190 |
"has_credits": false, |
|
| 191 |
"auth_token_expires": |
|
| 192 |
"Fri, 29 Jun 2012 10:03:37 GMT", |
|
| 193 |
"enabled": true, |
|
| 194 |
"email": ["user@example.com"], |
|
| 195 |
"id": 4} |
|
| 196 |
|
|
| 87 | 197 |
Get Services |
| 88 | 198 |
^^^^^^^^^^^^ |
| 89 | 199 |
|
| ... | ... | |
| 99 | 209 |
|
| 100 | 210 |
:: |
| 101 | 211 |
|
| 102 |
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "cloud"},
|
|
| 103 |
{"url": "/okeanos.html", "name": "~okeanos", "id": "okeanos"},
|
|
| 104 |
{"url": "/ui/", "name": "pithos+", "id": "pithos"}]
|
|
| 105 |
|
|
| 212 |
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"},
|
|
| 213 |
{"url": "/okeanos.html", "name": "~okeanos", "id": "2"},
|
|
| 214 |
{"url": "/ui/", "name": "pithos+", "id": "3"}]
|
|
| 215 |
|
|
| 216 |
|
|
| 106 | 217 |
Get Menu |
| 107 | 218 |
^^^^^^^^ |
| 108 | 219 |
|
| ... | ... | |
| 114 | 225 |
``/im/get_menu`` GET Get cloud bar menu |
| 115 | 226 |
==================== ========= ================== |
| 116 | 227 |
|
| 228 |
Example reply if request user is not authenticated: |
|
| 229 |
|
|
| 230 |
:: |
|
| 231 |
|
|
| 232 |
[{"url": "/im/", "name": "Sign in"}]
|
|
| 233 |
|
|
| 234 |
Example reply if request user is authenticated: |
|
| 235 |
|
|
| 236 |
:: |
|
| 237 |
|
|
| 238 |
[{"url": "/im/login", "name": "user@example.com"},
|
|
| 239 |
{"url": "/im/profile", "name": "My account"},
|
|
| 240 |
{"url": "/im/logout", "name": "Sign out"}]
|
|
| 241 |
|
|
| 242 |
Service API Operations |
|
| 243 |
---------------------- |
|
| 244 |
|
|
| 245 |
The operations described in this chapter allow services to access user information and perform specific tasks. |
|
| 246 |
|
|
| 247 |
The operations require a valid service token. |
|
| 248 |
|
|
| 249 |
Send feedback |
|
| 250 |
^^^^^^^^^^^^^ |
|
| 251 |
|
|
| 252 |
Via this operaton services can post user feedback requests. |
|
| 253 |
|
|
| 254 |
========================= ========= ================== |
|
| 255 |
Uri Method Description |
|
| 256 |
========================= ========= ================== |
|
| 257 |
``/im/service/feedback`` POST Send feedback |
|
| 258 |
========================= ========= ================== |
|
| 259 |
|
|
| 260 |
| |
|
| 261 |
|
|
| 262 |
==================== ============================ |
|
| 263 |
Request Header Name Value |
|
| 264 |
==================== ============================ |
|
| 265 |
X-Auth-Token Service Authentication token |
|
| 266 |
==================== ============================ |
|
| 267 |
|
|
| 117 | 268 |
| |
| 118 | 269 |
|
| 119 | 270 |
====================== ========================= |
| 120 | 271 |
Request Parameter Name Value |
| 121 | 272 |
====================== ========================= |
| 122 |
location Location to pass in the next parameter |
|
| 273 |
auth_token User token |
|
| 274 |
feedback_msg Feedback message |
|
| 275 |
feedback_data Additional information about service client status |
|
| 123 | 276 |
====================== ========================= |
| 124 | 277 |
|
| 125 |
Example reply if request user is not authenticated: |
|
| 278 |
| |
|
| 279 |
|
|
| 280 |
=========================== ===================== |
|
| 281 |
Return Code Description |
|
| 282 |
=========================== ===================== |
|
| 283 |
200 (OK) The request succeeded |
|
| 284 |
400 (Bad Request) Method not allowed or missing or invalid user token parameter or invalid message data |
|
| 285 |
401 (Unauthorized) Missing or expired service token |
|
| 286 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
| 287 |
=========================== ===================== |
|
| 288 |
|
|
| 289 |
Get User by email |
|
| 290 |
^^^^^^^^^^^^^^^^^ |
|
| 291 |
|
|
| 292 |
Returns a json formatted dictionary containing information about a specific user |
|
| 293 |
|
|
| 294 |
================================ ========= ================== |
|
| 295 |
Uri Method Description |
|
| 296 |
================================ ========= ================== |
|
| 297 |
``/im/service/api/v2.0/users/`` GET Get user information by email |
|
| 298 |
================================ ========= ================== |
|
| 299 |
|
|
| 300 |
| |
|
| 301 |
|
|
| 302 |
==================== ============================ |
|
| 303 |
Request Header Name Value |
|
| 304 |
==================== ============================ |
|
| 305 |
X-Auth-Token Service Authentication token |
|
| 306 |
==================== ============================ |
|
| 307 |
|
|
| 308 |
| |
|
| 309 |
|
|
| 310 |
====================== ========================= |
|
| 311 |
Request Parameter Name Value |
|
| 312 |
====================== ========================= |
|
| 313 |
name Email |
|
| 314 |
====================== ========================= |
|
| 315 |
|
|
| 316 |
| |
|
| 317 |
|
|
| 318 |
=========================== ===================== |
|
| 319 |
Return Code Description |
|
| 320 |
=========================== ===================== |
|
| 321 |
200 (OK) The request succeeded |
|
| 322 |
400 (Bad Request) Method not allowed |
|
| 323 |
401 (Unauthorized) Missing or expired or invalid service token |
|
| 324 |
404 (Not Found) Missing email or inactive user |
|
| 325 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
| 326 |
=========================== ===================== |
|
| 327 |
|
|
| 328 |
Example reply: |
|
| 126 | 329 |
|
| 127 | 330 |
:: |
| 128 | 331 |
|
| 129 |
[{"url": "/im/login?next=", "name": "login..."}]
|
|
| 332 |
{"username": "7e530044f90a4e7ba2cb94f3a26c40",
|
|
| 333 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT", |
|
| 334 |
"name": "Firstname Surname", |
|
| 335 |
"groups": ["default"], |
|
| 336 |
"user_permissions": [], |
|
| 337 |
"has_credits": false, |
|
| 338 |
"auth_token_expires":"Fri, 29 Jun 2012 10:03:37 GMT", |
|
| 339 |
"enabled": true, |
|
| 340 |
"email": ["user@example.com"], |
|
| 341 |
"id": 4} |
|
| 342 |
|
|
| 343 |
Get User by username |
|
| 344 |
^^^^^^^^^^^^^^^^^^^^ |
|
| 130 | 345 |
|
| 131 |
Example reply if request user is authenticated::
|
|
| 346 |
Returns a json formatted dictionary containing information about a specific user
|
|
| 132 | 347 |
|
| 133 |
[{"url": "/im/profile", "name": "user@grnet.gr"},
|
|
| 134 |
{"url": "/im/profile", "name": "view your profile..."},
|
|
| 135 |
{"url": "/im/password", "name": "change your password..."},
|
|
| 136 |
{"url": "/im/feedback", "name": "feedback..."},
|
|
| 137 |
{"url": "/im/logout", "name": "logout..."}]
|
|
| 348 |
========================================== ========= ================== |
|
| 349 |
Uri Method Description |
|
| 350 |
========================================== ========= ================== |
|
| 351 |
``/im/service/api/v2.0/users/{username}`` GET Get user information by username
|
|
| 352 |
========================================== ========= ================== |
|
| 353 |
|
|
| 354 |
| |
|
| 138 | 355 |
|
| 356 |
==================== ============================ |
|
| 357 |
Request Header Name Value |
|
| 358 |
==================== ============================ |
|
| 359 |
X-Auth-Token Service Authentication token |
|
| 360 |
==================== ============================ |
|
| 139 | 361 |
|
| 362 |
| |
|
| 140 | 363 |
|
| 364 |
=========================== ===================== |
|
| 365 |
Return Code Description |
|
| 366 |
=========================== ===================== |
|
| 367 |
200 (OK) The request succeeded |
|
| 368 |
400 (Bad Request) Method not allowed |
|
| 369 |
401 (Unauthorized) Missing or expired or invalid service token |
|
| 370 |
404 (Not Found) Invalid username |
|
| 371 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
| 372 |
=========================== ===================== |
|
| 373 |
|
|
| 374 |
Example reply: |
|
| 375 |
|
|
| 376 |
:: |
|
| 141 | 377 |
|
| 378 |
{"username": "7e530044f90a4e7ba2cb94f3a26c40",
|
|
| 379 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT", |
|
| 380 |
"name": "Firstname Surname", |
|
| 381 |
"groups": ["default"], |
|
| 382 |
"user_permissions": [], |
|
| 383 |
"has_credits": false, |
|
| 384 |
"auth_token_expires": |
|
| 385 |
"Fri, 29 Jun 2012 10:03:37 GMT", |
|
| 386 |
"enabled": true, |
|
| 387 |
"email": ["user@example.com"], |
|
| 388 |
"id": 4} |
|
Also available in: Unified diff