root / docs / cyclades-api-guide.rst @ 382ca20a
History | View | Annotate | Download (16.2 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** ignores ``personality`` of requests. |
120 |
* **Create Server** ignores the disk size of the flavor. |
121 |
* **Create Server** hardcodes the OS. |
122 |
* **Create Server** does not support setting the password in the request. |
123 |
|
124 |
List Servers |
125 |
............ |
126 |
|
127 |
* **List Servers** returns just ``id`` and ``name`` if details are not |
128 |
requested. |
129 |
* **List Servers** can return 304 (even though not explicitly stated) when |
130 |
``changes-since`` is given. |
131 |
|
132 |
**Example List Servers: JSON** |
133 |
|
134 |
.. code-block:: javascript |
135 |
|
136 |
{ |
137 |
'servers': |
138 |
{'values': [ |
139 |
{ |
140 |
'addresses': {'values': [ |
141 |
{ |
142 |
'id': 'public', |
143 |
'mac': 'aa:00:00:49:2e:7e', |
144 |
'name': 'public', |
145 |
'values': [ {'addr': '192.168.32.6', 'version': 4} ] |
146 |
} |
147 |
]}, |
148 |
'created': '2011-04-19T10:18:52.085737+00:00', |
149 |
'flavorRef': 1, |
150 |
'hostId': '', |
151 |
'id': 1, |
152 |
'imageRef': 3, |
153 |
'metadata': {'values': {'foo': 'bar'}}, |
154 |
'name': 'My Server', |
155 |
'status': 'ACTIVE', |
156 |
'updated': u'2011-05-29T14:07:07.037602+00:00' |
157 |
}, |
158 |
{ |
159 |
'addresses': {'values': [ |
160 |
{ |
161 |
'id': 'public', |
162 |
'mac': 'aa:00:00:91:2f:df', |
163 |
'name': 'public', |
164 |
'values': [ {'addr': '192.168.32.7', 'version': 4} ] |
165 |
}, |
166 |
{ |
167 |
'id': '2', |
168 |
'mac': 'aa:00:00:c3:69:6f', |
169 |
'name': 'private' |
170 |
}, |
171 |
]}, |
172 |
'created': '2011-05-02T20:51:08.527759+00:00', |
173 |
'flavorRef': 1, |
174 |
'hostId': '', |
175 |
'id': 2, |
176 |
'imageRef': 3, |
177 |
'name': 'Other Server', |
178 |
'progress': 0, |
179 |
'status': 'ACTIVE', |
180 |
'updated': '2011-05-29T14:59:11.267087+00:00' |
181 |
} |
182 |
] |
183 |
} |
184 |
} |
185 |
|
186 |
|
187 |
Get Server Stats |
188 |
................ |
189 |
|
190 |
**GET** /servers/*id*/stats |
191 |
|
192 |
**Normal Response Code**: 200 |
193 |
|
194 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
195 |
unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413) |
196 |
|
197 |
This operation returns URLs to graphs showing CPU and Network statistics. A |
198 |
``refresh`` attribute is returned as well that is the recommended refresh rate |
199 |
of the stats for the clients. |
200 |
|
201 |
This operation does not require a request body. |
202 |
|
203 |
**Example Get Server Stats Response: JSON**: |
204 |
|
205 |
.. code-block:: javascript |
206 |
|
207 |
{ |
208 |
"stats": { |
209 |
"serverRef": 1, |
210 |
"refresh": 60, |
211 |
"cpuBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png", |
212 |
"cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png", |
213 |
"netBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png", |
214 |
"netTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png" |
215 |
} |
216 |
} |
217 |
|
218 |
**Example Get Network Details Response: XML**: |
219 |
|
220 |
.. code-block:: xml |
221 |
|
222 |
<?xml version="1.0" encoding="UTF-8"?> |
223 |
<stats xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
224 |
serverRef="1" |
225 |
refresh="60" |
226 |
cpuBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png" |
227 |
cpuTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png" |
228 |
netBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png" |
229 |
netTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png"> |
230 |
</stats> |
231 |
|
232 |
|
233 |
Server Addresses |
234 |
---------------- |
235 |
|
236 |
Server Actions |
237 |
-------------- |
238 |
|
239 |
* **Change Password** is not supported. |
240 |
* **Rebuild Server** is not supported. |
241 |
* **Resize Server** is not supported. |
242 |
* **Confirm Resized Server** is not supported. |
243 |
* **Revert Resized Server** is not supported. |
244 |
|
245 |
We have have extended the API with the following commands: |
246 |
|
247 |
|
248 |
Start Server |
249 |
............ |
250 |
|
251 |
**Normal Response Code**: 202 |
252 |
|
253 |
**Error Response Codes**: serviceUnavailable (503), itemNotFound (404) |
254 |
|
255 |
The start function transitions a server from an ACTIVE to a STOPPED state. |
256 |
|
257 |
**Example Action Start: JSON**: |
258 |
|
259 |
.. code-block:: javascript |
260 |
|
261 |
{ |
262 |
"start": {} |
263 |
} |
264 |
|
265 |
This operation does not return a response body. |
266 |
|
267 |
|
268 |
Shutdown Server |
269 |
............... |
270 |
|
271 |
**Normal Response Code**: 202 |
272 |
|
273 |
**Error Response Codes**: serviceUnavailable (503), itemNotFound (404) |
274 |
|
275 |
The start function transitions a server from a STOPPED to an ACTIVE state. |
276 |
|
277 |
**Example Action Shutdown: JSON**: |
278 |
|
279 |
.. code-block:: javascript |
280 |
|
281 |
{ |
282 |
"shutdown": {} |
283 |
} |
284 |
|
285 |
This operation does not return a response body. |
286 |
|
287 |
|
288 |
Get Server Console |
289 |
|
290 |
**Normal Response Code**: 200 |
291 |
|
292 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), buildInProgress (409), overLimit (413) |
293 |
|
294 |
The console function arranges for an OOB console of the specified type. Only consoles of type "vnc" are supported for now. |
295 |
|
296 |
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. |
297 |
|
298 |
**Example Action Console: JSON**: |
299 |
|
300 |
.. code-block:: javascript |
301 |
|
302 |
{ |
303 |
"console": { |
304 |
"type": "vnc" |
305 |
} |
306 |
} |
307 |
|
308 |
**Example Action Console Response: JSON**: |
309 |
|
310 |
.. code-block:: javascript |
311 |
|
312 |
{ |
313 |
"console": { |
314 |
"type": "vnc", |
315 |
"host": "vm42.ocean.grnet.gr", |
316 |
"port": 1234, |
317 |
"password": "IN9RNmaV" |
318 |
} |
319 |
} |
320 |
|
321 |
**Example Action Console Response: XML**: |
322 |
|
323 |
.. code-block:: xml |
324 |
|
325 |
<?xml version="1.0" encoding="UTF-8"?> |
326 |
<console xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
327 |
type="vnc" |
328 |
host="vm42.ocean.grnet.gr" |
329 |
port="1234" |
330 |
password="IN9RNmaV"> |
331 |
</console> |
332 |
|
333 |
|
334 |
Set Firewall Profile |
335 |
.................... |
336 |
|
337 |
**Normal Response Code**: 202 |
338 |
|
339 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
340 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
341 |
buildInProgress (409), overLimit (413) |
342 |
|
343 |
The firewallProfile function sets a firewall profile for the public interface |
344 |
of a server. |
345 |
|
346 |
The allowed profiles are: **ENABLED**, **DISABLED** and **PROTECTED**. |
347 |
|
348 |
**Example Action firewallProfile: JSON**: |
349 |
|
350 |
.. code-block:: javascript |
351 |
|
352 |
{ |
353 |
"firewallProfile": { |
354 |
"profile": "ENABLED" |
355 |
} |
356 |
} |
357 |
|
358 |
This operation does not return a response body. |
359 |
|
360 |
|
361 |
Flavors |
362 |
------- |
363 |
|
364 |
* ``self`` and ``bookmark`` atom links are not returned. |
365 |
* **List Flavors** returns just ``id`` and ``name`` if details is not requested. |
366 |
|
367 |
|
368 |
Images |
369 |
------ |
370 |
|
371 |
* ``progress`` is always returned. |
372 |
* ``self`` and ``bookmark`` atom links are not returned. |
373 |
* **List Images** returns just ``id`` and ``name`` if details are not requested. |
374 |
* **List Images** can return 304 (even though not explicitly stated) when |
375 |
``changes-since`` is given. |
376 |
* **List Images** does not return deleted images when ``changes-since`` is given. |
377 |
|
378 |
|
379 |
Metadata |
380 |
-------- |
381 |
|
382 |
* **Update Server Metadata** and **Update Image Metadata** will only return the |
383 |
metadata that were updated (some could have been skipped). |
384 |
|
385 |
|
386 |
Networks |
387 |
-------- |
388 |
|
389 |
This is an extension to the OpenStack API. |
390 |
|
391 |
A Server can connect to one or more networks identified by a numeric id. Each |
392 |
user has access only to networks created by himself. When a network is deleted, |
393 |
all connections to it are deleted. Likewise, when a server is deleted, all |
394 |
connections of that server are deleted. |
395 |
|
396 |
There is a special **public** network with the id *public* that can be accessed |
397 |
at */networks/public*. All servers are connected to **public** by default and |
398 |
this network can not be deleted or modified in any way. |
399 |
|
400 |
|
401 |
List Networks |
402 |
............. |
403 |
|
404 |
**GET** /networks |
405 |
|
406 |
**GET** /networks/detail |
407 |
|
408 |
**Normal Response Codes**: 200, 203 |
409 |
|
410 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
411 |
unauthorized (401), badRequest (400), overLimit (413) |
412 |
|
413 |
This operation provides a list of private networks associated with your account. |
414 |
|
415 |
This operation does not require a request body. |
416 |
|
417 |
**Example Networks List Response: JSON (detail)**: |
418 |
|
419 |
.. code-block:: javascript |
420 |
|
421 |
{ |
422 |
"networks": { |
423 |
"values": [ |
424 |
{ |
425 |
"id": "public", |
426 |
"name": "public", |
427 |
"created": "2011-04-20T15:31:08.199640+00:00", |
428 |
"updated": "2011-05-06T12:47:05.582679+00:00", |
429 |
"servers": { |
430 |
"values": [1, 2, 3] |
431 |
} |
432 |
}, |
433 |
{ |
434 |
"id": 2, |
435 |
"name": "private", |
436 |
"created": "2011-04-20T14:32:08.199640+00:00", |
437 |
"updated": "2011-05-06T11:40:05.582679+00:00", |
438 |
"servers": { |
439 |
"values": [1] |
440 |
} |
441 |
} |
442 |
] |
443 |
} |
444 |
} |
445 |
|
446 |
**Example Networks List Response: XML (detail)**: |
447 |
|
448 |
.. code-block:: xml |
449 |
|
450 |
<?xml version="1.0" encoding="UTF-8"?> |
451 |
<networks xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"> |
452 |
<network id="public" name="public" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00"> |
453 |
<servers> |
454 |
<server id="1"></server> |
455 |
<server id="2"></server> |
456 |
<server id="3"></server> |
457 |
</servers> |
458 |
</network> |
459 |
<network id="2" name="private" updated="2011-05-06T12:47:05.582679+00:00" created="2011-04-20T15:31:33.911299+00:00"> |
460 |
<servers> |
461 |
<server id="1"></server> |
462 |
</servers> |
463 |
</network> |
464 |
</networks> |
465 |
|
466 |
|
467 |
Create Network |
468 |
.............. |
469 |
|
470 |
**POST** /networks |
471 |
|
472 |
**Normal Response Code**: 202 |
473 |
|
474 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
475 |
unauthorized (401), badMediaType(415), badRequest (400), overLimit (413) |
476 |
|
477 |
This operation asynchronously provisions a new private network. |
478 |
|
479 |
**Example Create Network Request: JSON**: |
480 |
|
481 |
.. code-block:: javascript |
482 |
|
483 |
{ |
484 |
"network": { |
485 |
"name": "private_net", |
486 |
} |
487 |
} |
488 |
|
489 |
**Example Create Network Response: JSON**: |
490 |
|
491 |
.. code-block:: javascript |
492 |
|
493 |
{ |
494 |
"network": { |
495 |
"id": 3, |
496 |
"name": "private_net", |
497 |
"created": "2011-04-20T15:31:08.199640+00:00", |
498 |
"servers": { |
499 |
"values": [] |
500 |
} |
501 |
} |
502 |
} |
503 |
|
504 |
**Example Create Network Response: XML**: |
505 |
|
506 |
.. code-block:: xml |
507 |
|
508 |
<?xml version="1.0" encoding="UTF-8"?> |
509 |
<network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
510 |
id="2" name="foob" created="2011-04-20T15:31:08.199640+00:00"> |
511 |
<servers> |
512 |
</servers> |
513 |
</network> |
514 |
|
515 |
|
516 |
Get Network Details |
517 |
................... |
518 |
|
519 |
**GET** /networks/*id* |
520 |
|
521 |
**Normal Response Codes**: 200, 203 |
522 |
|
523 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
524 |
unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413) |
525 |
|
526 |
This operation returns the details of a specific network by its id. |
527 |
|
528 |
This operation does not require a request body. |
529 |
|
530 |
**Example Get Network Details Response: JSON**: |
531 |
|
532 |
.. code-block:: javascript |
533 |
|
534 |
{ |
535 |
"network": { |
536 |
"id": 3, |
537 |
"name": "private_net", |
538 |
"servers": { |
539 |
"values": [1, 7] |
540 |
} |
541 |
} |
542 |
} |
543 |
|
544 |
**Example Get Network Details Response: XML**:: |
545 |
|
546 |
<?xml version="1.0" encoding="UTF-8"?> |
547 |
<network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom" |
548 |
id="2" name="foob" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00"> |
549 |
<servers> |
550 |
<server id="1"></server> |
551 |
<server id="7"></server> |
552 |
</servers> |
553 |
</network> |
554 |
|
555 |
|
556 |
Update Network Name |
557 |
................... |
558 |
|
559 |
**PUT** /networks/*id* |
560 |
|
561 |
**Normal Response Code**: 204 |
562 |
|
563 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
564 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
565 |
overLimit (413) |
566 |
|
567 |
This operation changes the name of the network in the Compute system. |
568 |
|
569 |
**Example Update Network Name Request: JSON**:: |
570 |
|
571 |
.. code-block:: javascript |
572 |
|
573 |
{ |
574 |
"network": { |
575 |
"name": "new_name" |
576 |
} |
577 |
} |
578 |
|
579 |
This operation does not contain a response body. |
580 |
|
581 |
|
582 |
Delete Network |
583 |
.............. |
584 |
|
585 |
**DELETE** /networks/*id* |
586 |
|
587 |
**Normal Response Code**: 204 |
588 |
|
589 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
590 |
unauthorized (401), itemNotFound (404), unauthorized (401), overLimit (413) |
591 |
|
592 |
This operation deletes a network from the system. |
593 |
|
594 |
This operation does not require a request or a response body. |
595 |
|
596 |
|
597 |
Network Actions |
598 |
--------------- |
599 |
|
600 |
Add Server |
601 |
.......... |
602 |
|
603 |
**POST** /networks/*id*/action |
604 |
|
605 |
**Normal Response Code**: 202 |
606 |
|
607 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
608 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
609 |
overLimit (413) |
610 |
|
611 |
This operation adds a server to the specified network. |
612 |
|
613 |
**Example Action Add: JSON**: |
614 |
|
615 |
.. code-block:: javascript |
616 |
|
617 |
{ |
618 |
"add" : { |
619 |
"serverRef" : 42 |
620 |
} |
621 |
} |
622 |
|
623 |
This operation does not contain a response body. |
624 |
|
625 |
|
626 |
Remove Server |
627 |
............. |
628 |
|
629 |
**POST** /networks/*id*/action |
630 |
|
631 |
**Normal Response Code**: 202 |
632 |
|
633 |
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), |
634 |
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), |
635 |
overLimit (413) |
636 |
|
637 |
This operation removes a server from the specified network. |
638 |
|
639 |
**Example Action Remove: JSON**: |
640 |
|
641 |
.. code-block:: javascript |
642 |
|
643 |
{ |
644 |
"remove" : { |
645 |
"serverRef" : 42 |
646 |
} |
647 |
} |
648 |
|
649 |
This operation does not contain a response body. |