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