Statistics
| Branch: | Tag: | Revision:

root / docs / cyclades-api-guide.rst @ 34e79416

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 `kamaki <http://www.synnefo.org/docs/kamaki/latest/index.html>`_
12
command-line client and associated python library can be used instead of making
13
direct calls to :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.