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