root / docs / astakos-api-guide.rst @ 8f9976c6
History | View | Annotate | Download (4.8 kB)
1 |
Astakos API |
---|---|
2 |
=========== |
3 |
|
4 |
This is Astakos API guide. |
5 |
|
6 |
Overview |
7 |
-------- |
8 |
|
9 |
Astakos serves as the point of authentication for GRNET (http://www.grnet.gr) |
10 |
services. It is a platform-wide service, allowing users to register, login, and |
11 |
keep track of permissions. |
12 |
|
13 |
Users in astakos can be authenticated via several identity providers: |
14 |
|
15 |
* Local |
16 |
|
17 |
* Shibboleth |
18 |
|
19 |
It provides also a command line tool for managing user accounts. |
20 |
|
21 |
It is build over django and extends its authentication mechanism. |
22 |
|
23 |
This document's goals is to describe the APIs to the outer world. |
24 |
Make sure you have read the :ref:`astakos` general architecture first. |
25 |
|
26 |
The present document is meant to be read alongside the Django documentation |
27 |
(https://www.djangoproject.com/). Thus, it is suggested that the reader is |
28 |
familiar with associated technologies. |
29 |
|
30 |
Document Revisions |
31 |
^^^^^^^^^^^^^^^^^^ |
32 |
|
33 |
========================= ================================ |
34 |
Revision Description |
35 |
========================= ================================ |
36 |
0.1 (Feb 10, 2012) Initial release. |
37 |
========================= ================================ |
38 |
|
39 |
API Operations |
40 |
-------------- |
41 |
|
42 |
.. _authenticate-api-label: |
43 |
|
44 |
Authenticate |
45 |
^^^^^^^^^^^^ |
46 |
|
47 |
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`) |
48 |
|
49 |
==================== ========= ================== |
50 |
Uri Method Description |
51 |
==================== ========= ================== |
52 |
``/im/authenticate`` GET Authenticate user using token |
53 |
==================== ========= ================== |
54 |
|
55 |
| |
56 |
|
57 |
==================== =========================== |
58 |
Request Header Name Value |
59 |
==================== =========================== |
60 |
X-Auth-Token Authentication token |
61 |
==================== =========================== |
62 |
|
63 |
Extended information on the user serialized in the json format will be returned: |
64 |
|
65 |
=========================== ============================ |
66 |
Name Description |
67 |
=========================== ============================ |
68 |
username User uniq identifier |
69 |
uniq User email (uniq identifier used by Astakos) |
70 |
auth_token Authentication token |
71 |
auth_token_expires Token expiration date |
72 |
auth_token_created Token creation date |
73 |
has_credits Whether user has credits |
74 |
has_signed_terms Whether user has aggred on terms |
75 |
=========================== ============================ |
76 |
|
77 |
Example reply: |
78 |
|
79 |
:: |
80 |
|
81 |
{"username": "4ad9f34d6e7a4992b34502d40f40cb", |
82 |
"uniq": "papagian@example.com" |
83 |
"auth_token": "0000", |
84 |
"auth_token_expires": "Tue, 11-Sep-2012 09:17:14 ", |
85 |
"auth_token_created": "Sun, 11-Sep-2011 09:17:14 ", |
86 |
"has_credits": false, |
87 |
"has_signed_terms": true} |
88 |
|
89 |
| |
90 |
|
91 |
=========================== ===================== |
92 |
Return Code Description |
93 |
=========================== ===================== |
94 |
204 (No Content) The request succeeded |
95 |
400 (Bad Request) The request is invalid |
96 |
401 (Unauthorized) Missing token or inactive user or penging approval terms |
97 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
98 |
=========================== ===================== |
99 |
|
100 |
Get Services |
101 |
^^^^^^^^^^^^ |
102 |
|
103 |
Returns a json formatted list containing information about the supported cloud services. |
104 |
|
105 |
==================== ========= ================== |
106 |
Uri Method Description |
107 |
==================== ========= ================== |
108 |
``/im/get_services`` GET Get cloud services |
109 |
==================== ========= ================== |
110 |
|
111 |
Example reply: |
112 |
|
113 |
:: |
114 |
|
115 |
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "cloud"}, |
116 |
{"url": "/okeanos.html", "name": "~okeanos", "id": "okeanos"}, |
117 |
{"url": "/ui/", "name": "pithos+", "id": "pithos"}] |
118 |
|
119 |
Get Menu |
120 |
^^^^^^^^ |
121 |
|
122 |
Returns a json formatted list containing the cloud bar links. |
123 |
|
124 |
==================== ========= ================== |
125 |
Uri Method Description |
126 |
==================== ========= ================== |
127 |
``/im/get_menu`` GET Get cloud bar menu |
128 |
==================== ========= ================== |
129 |
|
130 |
| |
131 |
|
132 |
====================== ========================= |
133 |
Request Parameter Name Value |
134 |
====================== ========================= |
135 |
location Location to pass in the next parameter |
136 |
====================== ========================= |
137 |
|
138 |
Example reply if request user is not authenticated: |
139 |
|
140 |
:: |
141 |
|
142 |
[{"url": "/im/login?next=", "name": "login..."}] |
143 |
|
144 |
Example reply if request user is authenticated: |
145 |
|
146 |
[{"url": "/im/profile", "name": "spapagian@grnet.gr"}, |
147 |
{"url": "/im/profile", "name": "view your profile..."}, |
148 |
{"url": "/im/password", "name": "change your password..."}, |
149 |
{"url": "/im/feedback", "name": "feedback..."}, |
150 |
{"url": "/im/logout", "name": "logout..."}] |
151 |
|
152 |
|
153 |
|
154 |
|