root / docs / astakos-api-guide.rst @ 6609821f
History | View | Annotate | Download (10.8 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 14, 2013) Do not serve user quotas in :ref:`authenticate-api-label` |
24 |
0.14 (May 02, 2013) Change URIs (keep also the old ones until the next version) |
25 |
0.13 (January 21, 2013) Extend api to export user presentation & quota information. |
26 |
0.6 (June 06, 2012) Split service and user API. |
27 |
0.1 (Feb 10, 2012) Initial release. |
28 |
========================= ================================ |
29 |
|
30 |
Get Services |
31 |
^^^^^^^^^^^^ |
32 |
|
33 |
Returns a json formatted list containing information about the supported cloud services. |
34 |
|
35 |
============================= ========= ================== |
36 |
Uri Method Description |
37 |
============================= ========= ================== |
38 |
``/astakos/api/get_services`` GET Get cloud services |
39 |
============================= ========= ================== |
40 |
|
41 |
Example reply: |
42 |
|
43 |
:: |
44 |
|
45 |
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"}, |
46 |
{"url": "/okeanos.html", "name": "~okeanos", "id": "2"}, |
47 |
{"url": "/ui/", "name": "pithos+", "id": "3"}] |
48 |
|
49 |
.. warning:: The service is also available under ``/im/get_services``. |
50 |
It will be removed in the next version. |
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 |
``/astakos/api/get_menu`` GET Get cloud bar menu |
62 |
========================= ========= ================== |
63 |
|
64 |
Example reply if request user is not authenticated: |
65 |
|
66 |
:: |
67 |
|
68 |
[{"url": "/im/", "name": "Sign in"}] |
69 |
|
70 |
Example reply if request user is authenticated: |
71 |
|
72 |
:: |
73 |
|
74 |
[{"url": "/im/", "name": "user@example.com"}, |
75 |
{"url": "/im/landing", "name": "Dashboard"}, |
76 |
{"url": "/im/logout", "name": "Sign out"}] |
77 |
|
78 |
.. warning:: The service is also available under ``/im/get_menu``. |
79 |
It will be removed in the next version. |
80 |
|
81 |
User API Operations |
82 |
-------------------- |
83 |
|
84 |
The operations described in this chapter allow users to authenticate themselves, send feedback and get user uuid/displayname mappings. |
85 |
|
86 |
All the operations require a valid user token. |
87 |
|
88 |
.. _authenticate-api-label: |
89 |
|
90 |
Authenticate |
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 |
Uri Method Description |
97 |
============================= ========= ================== |
98 |
``/astakos/api/authenticate`` GET Authenticate user using token |
99 |
============================= ========= ================== |
100 |
|
101 |
| |
102 |
|
103 |
==================== =========================== |
104 |
Request Header Name Value |
105 |
==================== =========================== |
106 |
X-Auth-Token User authentication token |
107 |
==================== =========================== |
108 |
|
109 |
Extended information on the user serialized in the json format will be returned: |
110 |
|
111 |
=========================== ============================ |
112 |
Name Description |
113 |
=========================== ============================ |
114 |
displayname User displayname |
115 |
uuid User unique identifier |
116 |
email List with user emails |
117 |
name User full name |
118 |
auth_token_created Token creation date |
119 |
auth_token_expires Token expiration date |
120 |
usage List of user resource usage (if usage request parameter is present) |
121 |
=========================== ============================ |
122 |
|
123 |
Example reply: |
124 |
|
125 |
:: |
126 |
|
127 |
{"id": "12", |
128 |
"displayname": "user@example.com", |
129 |
"uuid": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
130 |
"email": "[user@example.com]", |
131 |
"name": "Firstname Lastname", |
132 |
"auth_token_created": "Wed, 30 May 2012 10:03:37 GMT", |
133 |
"auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT"} |
134 |
|
135 |
| |
136 |
|
137 |
=========================== ===================== |
138 |
Return Code Description |
139 |
=========================== ===================== |
140 |
204 (No Content) The request succeeded |
141 |
400 (Bad Request) Method not allowed or no user found |
142 |
401 (Unauthorized) Missing token or inactive user or penging approval terms |
143 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
144 |
=========================== ===================== |
145 |
|
146 |
.. warning:: The service is also available under ``/im/authenticate``. |
147 |
It will be removed in the next version. |
148 |
|
149 |
|
150 |
Send feedback |
151 |
^^^^^^^^^^^^^ |
152 |
|
153 |
Post user feedback. |
154 |
|
155 |
========================= ========= ================== |
156 |
Uri Method Description |
157 |
========================= ========= ================== |
158 |
``/astakos/api/feedback`` POST Send feedback |
159 |
========================= ========= ================== |
160 |
|
161 |
| |
162 |
|
163 |
==================== ============================ |
164 |
Request Header Name Value |
165 |
==================== ============================ |
166 |
X-Auth-Token User authentication token |
167 |
==================== ============================ |
168 |
|
169 |
| |
170 |
|
171 |
====================== ========================= |
172 |
Request Parameter Name Value |
173 |
====================== ========================= |
174 |
feedback_msg Feedback message |
175 |
feedback_data Additional information about service client status |
176 |
====================== ========================= |
177 |
|
178 |
| |
179 |
|
180 |
=========================== ===================== |
181 |
Return Code Description |
182 |
=========================== ===================== |
183 |
200 (OK) The request succeeded |
184 |
502 (Bad Gateway) Send feedback failure |
185 |
400 (Bad Request) Method not allowed or invalid message data |
186 |
401 (Unauthorized) Missing or expired user token |
187 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
188 |
=========================== ===================== |
189 |
|
190 |
.. warning:: The service is also available under ``/feedback``. |
191 |
It will be removed in the next version. |
192 |
|
193 |
Get User catalogs |
194 |
^^^^^^^^^^^^^^^^^ |
195 |
|
196 |
Return a json formatted dictionary containing information about a specific user |
197 |
|
198 |
================================ ========= ================== |
199 |
Uri Method Description |
200 |
================================ ========= ================== |
201 |
``/astakos/api/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
202 |
================================ ========= ================== |
203 |
|
204 |
| |
205 |
|
206 |
==================== ============================ |
207 |
Request Header Name Value |
208 |
==================== ============================ |
209 |
X-Auth-Token User authentication token |
210 |
==================== ============================ |
211 |
|
212 |
| |
213 |
|
214 |
The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
215 |
|
216 |
Example request content: |
217 |
|
218 |
:: |
219 |
|
220 |
{"displaynames": ["user1@example.com", "user2@example.com"], |
221 |
"uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
222 |
|
223 |
Example reply: |
224 |
|
225 |
:: |
226 |
|
227 |
{"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
228 |
"user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
229 |
'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
230 |
"ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
231 |
|
232 |
|
233 |
| |
234 |
|
235 |
=========================== ===================== |
236 |
Return Code Description |
237 |
=========================== ===================== |
238 |
200 (OK) The request succeeded |
239 |
400 (Bad Request) Method not allowed or request body is not json formatted |
240 |
401 (Unauthorized) Missing or expired or invalid user token |
241 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
242 |
=========================== ===================== |
243 |
|
244 |
.. warning:: The service is also available under ``/user_catalogs``. |
245 |
It will be removed in the next version. |
246 |
|
247 |
Service API Operations |
248 |
---------------------- |
249 |
|
250 |
The operations described in this chapter allow services to get user uuid/displayname mappings. |
251 |
|
252 |
All the operations require a valid service token. |
253 |
|
254 |
Get User catalogs |
255 |
^^^^^^^^^^^^^^^^^ |
256 |
|
257 |
Return a json formatted dictionary containing information about a specific user |
258 |
|
259 |
===================================== ========= ================== |
260 |
Uri Method Description |
261 |
===================================== ========= ================== |
262 |
``/astakos/api/service/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
263 |
===================================== ========= ================== |
264 |
|
265 |
| |
266 |
|
267 |
==================== ============================ |
268 |
Request Header Name Value |
269 |
==================== ============================ |
270 |
X-Auth-Token Service authentication token |
271 |
==================== ============================ |
272 |
|
273 |
| |
274 |
|
275 |
The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
276 |
If instead of list null is passed then the response contains the information for all the system users (For discretion purposes |
277 |
this behavior is **not** exposed in the respective call of the User API). |
278 |
|
279 |
Example request content: |
280 |
|
281 |
:: |
282 |
|
283 |
{"displaynames": ["user1@example.com", "user2@example.com"], |
284 |
"uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
285 |
|
286 |
Example reply: |
287 |
|
288 |
:: |
289 |
|
290 |
{"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
291 |
"user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
292 |
'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
293 |
"ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
294 |
|
295 |
|
296 |
| |
297 |
|
298 |
=========================== ===================== |
299 |
Return Code Description |
300 |
=========================== ===================== |
301 |
200 (OK) The request succeeded |
302 |
400 (Bad Request) Method not allowed or request body is not json formatted |
303 |
401 (Unauthorized) Missing or expired or invalid service token |
304 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
305 |
=========================== ===================== |
306 |
|
307 |
.. warning:: The service is also available under ``/service/api/user_catalogs``. |
308 |
It will be removed in the next version. |