root / docs / cyclades-api-guide.rst @ d7841399
History | View | Annotate | Download (16 kB)
1 |
.. _cyclades-api-guide: |
---|---|
2 |
|
3 |
API Guide |
4 |
********* |
5 |
|
6 |
.. todo:: Document the relation of the API to the OpenStack API v1.1. |
7 |
|
8 |
This is the guide to the REST API of the synnefo Compute Service. |
9 |
It is meant for users wishing to make calls to the REST API directly. |
10 |
|
11 |
The :ref:`kamaki <http://docs.dev.grnet.gr/kamaki>` command-line client |
12 |
and associated python library can be used instead of making direct calls to |
13 |
:ref:`cyclades <cyclades>`. |
14 |
|
15 |
Overview |
16 |
======== |
17 |
|
18 |
* It is not defined if requests for invalid URLs should return 404 or a Fault. |
19 |
We return a BadRequest Fault. |
20 |
* It is not defined if requests with a wrong HTTP method should return 405 or a |
21 |
Fault. We return a BadRequest Fault. |
22 |
|
23 |
|
24 |
General API Information |
25 |
======================= |
26 |
|
27 |
Authentication |
28 |
-------------- |
29 |
|
30 |
* Authentication support is missing. |
31 |
|
32 |
|
33 |
Request/Response Types |
34 |
---------------------- |
35 |
|
36 |
* We only support JSON Requests and JSON/XML Responses. XML Requests are not |
37 |
supported for now. |
38 |
|
39 |
|
40 |
Content Compression |
41 |
------------------- |
42 |
|
43 |
* Optional content compression support is missing. |
44 |
|
45 |
|
46 |
Persistent Connections |
47 |
---------------------- |
48 |
|
49 |
* Deployment note: "To prevent abuse, HTTP sessions have a timeout of 20 |
50 |
seconds before being closed." |
51 |
|
52 |
|
53 |
Links and References |
54 |
-------------------- |
55 |
|
56 |
* Full URI references support is missing. |
57 |
* Self and bookmark links support is missing. |
58 |
|
59 |
|
60 |
Paginated Collections |
61 |
--------------------- |
62 |
|
63 |
* Pagination support is missing. |
64 |
|
65 |
|
66 |
Caching |
67 |
------- |
68 |
|
69 |
* We do not return cached responses. |
70 |
|
71 |
|
72 |
Limits |
73 |
------ |
74 |
|
75 |
* Limits support is missing. |
76 |
|
77 |
|
78 |
Efficient Polling with the Changes-Since Parameter |
79 |
-------------------------------------------------- |
80 |
|
81 |
* We only support the changes-since parameter in **List Servers** and **List |
82 |
Images**. |
83 |
* We assume that garbage collection of deleted servers will only affect servers |
84 |
deleted ``POLL_TIME`` seconds in the past or earlier. Else we lose the |
85 |
information of a server getting deleted. |
86 |
* Images do not support a deleted state, so we can not track deletions. |
87 |
|
88 |
|
89 |
Versions |
90 |
-------- |
91 |
|
92 |
* Version MIME type support is missing. |
93 |
* Versionless requests are not supported. |
94 |
* We hardcode the ``updated`` field in versions list |
95 |
* Deployment note: The Atom metadata need to be fixed |
96 |
|
97 |
|
98 |
Extensions |
99 |
---------- |
100 |
|
101 |
* Extensions support is missing. |
102 |
|
103 |
|
104 |
Faults |
105 |
------ |
106 |
|
107 |
|
108 |
API Operations |
109 |
============== |
110 |
|
111 |
Servers |
112 |
------- |
113 |
|
114 |
* ``hostId`` is always empty. |
115 |
* ``affinityId`` is not returned. |
116 |
* ``progress`` is always returned. |
117 |
* ``self`` and ``bookmark`` atom links are not returned. |
118 |
* **Get Server Details** will also return servers with a DELETED state. |
119 |
* **Create Server** does not support setting the password in the request. |
120 |
|
121 |
List Servers |
122 |
............ |
123 |
|
124 |
* **List Servers** returns just ``id`` and ``name`` if details are not |
125 |
requested. |
126 |
* **List Servers** can return 304 (even though not explicitly stated) when |
127 |
``changes-since`` is given. |
128 |
|
129 |
**Example List Servers: JSON** |
130 |
|
131 |
.. code-block:: javascript |
132 |
|
133 |
{ |
134 |
'servers': |
135 |
{'values': [ |
136 |
{ |
137 |
'addresses': {'values': [ |
138 |
{ |
139 |
'id': 'public', |
140 |
'mac': 'aa:00:00:49:2e:7e', |
141 |
'name': 'public', |
142 |
'values': [ {'addr': '192.168.32.6', 'version': 4} ] |
143 |
} |
144 |
]}, |
145 |
'created': '2011-04-19T10:18:52.085737+00:00', |
146 |
'flavorRef': 1, |
147 |
'hostId': '', |
148 |
'id': 1, |
149 |
'imageRef': 3, |
150 |
'metadata': {'values': {'foo': 'bar'}}, |
151 |
'name': 'My Server', |
152 |
'status': 'ACTIVE', |
153 |
'updated': u'2011-05-29T14:07:07.037602+00:00' |
154 |
}, |
155 |
{ |
156 |
'addresses': {'values': [ |
157 |
{ |
158 |
'id': 'public', |
159 |
'mac': 'aa:00:00:91:2f:df', |
160 |
'name': 'public', |
161 |
'values': [ {'addr': '192.168.32.7', 'version': 4} ] |
162 |
}, |
163 |
{ |
164 |
'id': '2', |
165 |
'mac': 'aa:00:00:c3:69:6f', |
166 |
'name': 'private' |
167 |
}, |
168 |
]}, |
169 |
'created': '2011-05-02T20:51:08.527759+00:00', |
170 |
'flavorRef': 1, |
171 |
'hostId': '', |
172 |
'id': 2, |
173 |
'imageRef': 3, |
174 |
'name': 'Other Server', |
175 |
'progress': 0, |
176 |
'status': 'ACTIVE', |
177 |
'updated': '2011-05-29T14:59:11.267087+00:00' |
178 |
} |
179 |
] |
180 |
} |
181 |
} |
182 |
|
183 |
|
184 |
Get Server Stats |
185 |
................ |
186 |
|
187 |
**GET** /servers/*id*/stats |
188 |
|
189 |
**Normal Response Code**: 200 |
190 |
|
191 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
192 |
unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413) |
193 |
|
194 |
This operation returns URLs to graphs showing CPU and Network statistics. A |
195 |
``refresh`` attribute is returned as well that is the recommended refresh rate |
196 |
of the stats for the clients. |
197 |
|
198 |
This operation does not require a request body. |
199 |
|
200 |
**Example Get Server Stats Response: JSON**: |
201 |
|
202 |
.. code-block:: javascript |
203 |
|
204 |
{ |
205 |
"stats": { |
206 |
"serverRef": 1, |
207 |
"refresh": 60, |
208 |
"cpuBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png", |
209 |
"cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png", |
210 |
"netBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png", |
211 |
"netTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png" |
212 |
} |
213 |
} |
214 |
|
215 |
**Example Get Network Details Response: XML**: |
216 |
|
217 |
.. code-block:: xml |
218 |
|
219 |
<?xml version="1.0" encoding="UTF-8"?> |
220 |
<stats xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
221 |
serverRef="1" |
222 |
refresh="60" |
223 |
cpuBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png" |
224 |
cpuTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png" |
225 |
netBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png" |
226 |
netTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png"> |
227 |
</stats> |
228 |
|
229 |
|
230 |
Server Addresses |
231 |
---------------- |
232 |
|
233 |
Server Actions |
234 |
-------------- |
235 |
|
236 |
* **Change Password** is not supported. |
237 |
* **Rebuild Server** is not supported. |
238 |
* **Resize Server** is not supported. |
239 |
* **Confirm Resized Server** is not supported. |
240 |
* **Revert Resized Server** is not supported. |
241 |
|
242 |
We have have extended the API with the following commands: |
243 |
|
244 |
|
245 |
Start Server |
246 |
............ |
247 |
|
248 |
**Normal Response Code**: 202 |
249 |
|
250 |
**Error Response Codes**: serviceUnavailable (503), itemNotFound (404) |
251 |
|
252 |
The start function transitions a server from an ACTIVE to a STOPPED state. |
253 |
|
254 |
**Example Action Start: JSON**: |
255 |
|
256 |
.. code-block:: javascript |
257 |
|
258 |
{ |
259 |
"start": {} |
260 |
} |
261 |
|
262 |
This operation does not return a response body. |
263 |
|
264 |
|
265 |
Shutdown Server |
266 |
............... |
267 |
|
268 |
**Normal Response Code**: 202 |
269 |
|
270 |
**Error Response Codes**: serviceUnavailable (503), itemNotFound (404) |
271 |
|
272 |
The start function transitions a server from a STOPPED to an ACTIVE state. |
273 |
|
274 |
**Example Action Shutdown: JSON**: |
275 |
|
276 |
.. code-block:: javascript |
277 |
|
278 |
{ |
279 |
"shutdown": {} |
280 |
} |
281 |
|
282 |
This operation does not return a response body. |
283 |
|
284 |
|
285 |
Get Server Console |
286 |
|
287 |
**Normal Response Code**: 200 |
288 |
|
289 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), buildInProgress (409), overLimit (413) |
290 |
|
291 |
The console function arranges for an OOB console of the specified type. Only consoles of type "vnc" are supported for now. |
292 |
|
293 |
It uses a running instance of vncauthproxy to setup proper VNC forwarding with a random password, then returns the necessary VNC connection info to the caller. |
294 |
|
295 |
**Example Action Console: JSON**: |
296 |
|
297 |
.. code-block:: javascript |
298 |
|
299 |
{ |
300 |
"console": { |
301 |
"type": "vnc" |
302 |
} |
303 |
} |
304 |
|
305 |
**Example Action Console Response: JSON**: |
306 |
|
307 |
.. code-block:: javascript |
308 |
|
309 |
{ |
310 |
"console": { |
311 |
"type": "vnc", |
312 |
"host": "vm42.ocean.grnet.gr", |
313 |
"port": 1234, |
314 |
"password": "IN9RNmaV" |
315 |
} |
316 |
} |
317 |
|
318 |
**Example Action Console Response: XML**: |
319 |
|
320 |
.. code-block:: xml |
321 |
|
322 |
<?xml version="1.0" encoding="UTF-8"?> |
323 |
<console xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
324 |
type="vnc" |
325 |
host="vm42.ocean.grnet.gr" |
326 |
port="1234" |
327 |
password="IN9RNmaV"> |
328 |
</console> |
329 |
|
330 |
|
331 |
Set Firewall Profile |
332 |
.................... |
333 |
|
334 |
**Normal Response Code**: 202 |
335 |
|
336 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
337 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
338 |
buildInProgress (409), overLimit (413) |
339 |
|
340 |
The firewallProfile function sets a firewall profile for the public interface |
341 |
of a server. |
342 |
|
343 |
The allowed profiles are: **ENABLED**, **DISABLED** and **PROTECTED**. |
344 |
|
345 |
**Example Action firewallProfile: JSON**: |
346 |
|
347 |
.. code-block:: javascript |
348 |
|
349 |
{ |
350 |
"firewallProfile": { |
351 |
"profile": "ENABLED" |
352 |
} |
353 |
} |
354 |
|
355 |
This operation does not return a response body. |
356 |
|
357 |
|
358 |
Flavors |
359 |
------- |
360 |
|
361 |
* ``self`` and ``bookmark`` atom links are not returned. |
362 |
* **List Flavors** returns just ``id`` and ``name`` if details is not requested. |
363 |
|
364 |
|
365 |
Images |
366 |
------ |
367 |
|
368 |
* ``progress`` is always returned. |
369 |
* ``self`` and ``bookmark`` atom links are not returned. |
370 |
* **List Images** returns just ``id`` and ``name`` if details are not requested. |
371 |
* **List Images** can return 304 (even though not explicitly stated) when |
372 |
``changes-since`` is given. |
373 |
* **List Images** does not return deleted images when ``changes-since`` is given. |
374 |
|
375 |
|
376 |
Metadata |
377 |
-------- |
378 |
|
379 |
* **Update Server Metadata** and **Update Image Metadata** will only return the |
380 |
metadata that were updated (some could have been skipped). |
381 |
|
382 |
|
383 |
Networks |
384 |
-------- |
385 |
|
386 |
This is an extension to the OpenStack API. |
387 |
|
388 |
A Server can connect to one or more networks identified by a numeric id. Each |
389 |
user has access only to networks created by himself. When a network is deleted, |
390 |
all connections to it are deleted. Likewise, when a server is deleted, all |
391 |
connections of that server are deleted. |
392 |
|
393 |
There is a special **public** network with the id *public* that can be accessed |
394 |
at */networks/public*. All servers are connected to **public** by default and |
395 |
this network can not be deleted or modified in any way. |
396 |
|
397 |
|
398 |
List Networks |
399 |
............. |
400 |
|
401 |
**GET** /networks |
402 |
|
403 |
**GET** /networks/detail |
404 |
|
405 |
**Normal Response Codes**: 200, 203 |
406 |
|
407 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
408 |
unauthorized (401), badRequest (400), overLimit (413) |
409 |
|
410 |
This operation provides a list of private networks associated with your account. |
411 |
|
412 |
This operation does not require a request body. |
413 |
|
414 |
**Example Networks List Response: JSON (detail)**: |
415 |
|
416 |
.. code-block:: javascript |
417 |
|
418 |
{ |
419 |
"networks": { |
420 |
"values": [ |
421 |
{ |
422 |
"id": "public", |
423 |
"name": "public", |
424 |
"created": "2011-04-20T15:31:08.199640+00:00", |
425 |
"updated": "2011-05-06T12:47:05.582679+00:00", |
426 |
"servers": { |
427 |
"values": [1, 2, 3] |
428 |
} |
429 |
}, |
430 |
{ |
431 |
"id": 2, |
432 |
"name": "private", |
433 |
"created": "2011-04-20T14:32:08.199640+00:00", |
434 |
"updated": "2011-05-06T11:40:05.582679+00:00", |
435 |
"servers": { |
436 |
"values": [1] |
437 |
} |
438 |
} |
439 |
] |
440 |
} |
441 |
} |
442 |
|
443 |
**Example Networks List Response: XML (detail)**: |
444 |
|
445 |
.. code-block:: xml |
446 |
|
447 |
<?xml version="1.0" encoding="UTF-8"?> |
448 |
<networks xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"> |
449 |
<network id="public" name="public" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00"> |
450 |
<servers> |
451 |
<server id="1"></server> |
452 |
<server id="2"></server> |
453 |
<server id="3"></server> |
454 |
</servers> |
455 |
</network> |
456 |
<network id="2" name="private" updated="2011-05-06T12:47:05.582679+00:00" created="2011-04-20T15:31:33.911299+00:00"> |
457 |
<servers> |
458 |
<server id="1"></server> |
459 |
</servers> |
460 |
</network> |
461 |
</networks> |
462 |
|
463 |
|
464 |
Create Network |
465 |
.............. |
466 |
|
467 |
**POST** /networks |
468 |
|
469 |
**Normal Response Code**: 202 |
470 |
|
471 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
472 |
unauthorized (401), badMediaType(415), badRequest (400), overLimit (413) |
473 |
|
474 |
This operation asynchronously provisions a new private network. |
475 |
|
476 |
**Example Create Network Request: JSON**: |
477 |
|
478 |
.. code-block:: javascript |
479 |
|
480 |
{ |
481 |
"network": { |
482 |
"name": "private_net", |
483 |
} |
484 |
} |
485 |
|
486 |
**Example Create Network Response: JSON**: |
487 |
|
488 |
.. code-block:: javascript |
489 |
|
490 |
{ |
491 |
"network": { |
492 |
"id": 3, |
493 |
"name": "private_net", |
494 |
"created": "2011-04-20T15:31:08.199640+00:00", |
495 |
"servers": { |
496 |
"values": [] |
497 |
} |
498 |
} |
499 |
} |
500 |
|
501 |
**Example Create Network Response: XML**: |
502 |
|
503 |
.. code-block:: xml |
504 |
|
505 |
<?xml version="1.0" encoding="UTF-8"?> |
506 |
<network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
507 |
id="2" name="foob" created="2011-04-20T15:31:08.199640+00:00"> |
508 |
<servers> |
509 |
</servers> |
510 |
</network> |
511 |
|
512 |
|
513 |
Get Network Details |
514 |
................... |
515 |
|
516 |
**GET** /networks/*id* |
517 |
|
518 |
**Normal Response Codes**: 200, 203 |
519 |
|
520 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
521 |
unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413) |
522 |
|
523 |
This operation returns the details of a specific network by its id. |
524 |
|
525 |
This operation does not require a request body. |
526 |
|
527 |
**Example Get Network Details Response: JSON**: |
528 |
|
529 |
.. code-block:: javascript |
530 |
|
531 |
{ |
532 |
"network": { |
533 |
"id": 3, |
534 |
"name": "private_net", |
535 |
"servers": { |
536 |
"values": [1, 7] |
537 |
} |
538 |
} |
539 |
} |
540 |
|
541 |
**Example Get Network Details Response: XML**:: |
542 |
|
543 |
<?xml version="1.0" encoding="UTF-8"?> |
544 |
<network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
545 |
id="2" name="foob" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00"> |
546 |
<servers> |
547 |
<server id="1"></server> |
548 |
<server id="7"></server> |
549 |
</servers> |
550 |
</network> |
551 |
|
552 |
|
553 |
Update Network Name |
554 |
................... |
555 |
|
556 |
**PUT** /networks/*id* |
557 |
|
558 |
**Normal Response Code**: 204 |
559 |
|
560 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
561 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
562 |
overLimit (413) |
563 |
|
564 |
This operation changes the name of the network in the Compute system. |
565 |
|
566 |
**Example Update Network Name Request: JSON**:: |
567 |
|
568 |
.. code-block:: javascript |
569 |
|
570 |
{ |
571 |
"network": { |
572 |
"name": "new_name" |
573 |
} |
574 |
} |
575 |
|
576 |
This operation does not contain a response body. |
577 |
|
578 |
|
579 |
Delete Network |
580 |
.............. |
581 |
|
582 |
**DELETE** /networks/*id* |
583 |
|
584 |
**Normal Response Code**: 204 |
585 |
|
586 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
587 |
unauthorized (401), itemNotFound (404), unauthorized (401), overLimit (413) |
588 |
|
589 |
This operation deletes a network from the system. |
590 |
|
591 |
This operation does not require a request or a response body. |
592 |
|
593 |
|
594 |
Network Actions |
595 |
--------------- |
596 |
|
597 |
Add Server |
598 |
.......... |
599 |
|
600 |
**POST** /networks/*id*/action |
601 |
|
602 |
**Normal Response Code**: 202 |
603 |
|
604 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
605 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
606 |
overLimit (413) |
607 |
|
608 |
This operation adds a server to the specified network. |
609 |
|
610 |
**Example Action Add: JSON**: |
611 |
|
612 |
.. code-block:: javascript |
613 |
|
614 |
{ |
615 |
"add" : { |
616 |
"serverRef" : 42 |
617 |
} |
618 |
} |
619 |
|
620 |
This operation does not contain a response body. |
621 |
|
622 |
|
623 |
Remove Server |
624 |
............. |
625 |
|
626 |
**POST** /networks/*id*/action |
627 |
|
628 |
**Normal Response Code**: 202 |
629 |
|
630 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
631 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
632 |
overLimit (413) |
633 |
|
634 |
This operation removes a server from the specified network. |
635 |
|
636 |
**Example Action Remove: JSON**: |
637 |
|
638 |
.. code-block:: javascript |
639 |
|
640 |
{ |
641 |
"remove" : { |
642 |
"serverRef" : 42 |
643 |
} |
644 |
} |
645 |
|
646 |
This operation does not contain a response body. |