cyclades-api-guide.rst 60 KB
Newer Older
1
2
.. _cyclades-api-guide:

3
4
5
API Guide
*********

6
7
8
9
`Cyclades <cyclades.html>`_ is the compute service developed by `GRNET 
<http://www.grnet.gr>`_ as part of the `synnefo <http://www.synnefo.org>`_
software, that implements an extension of the `OpenStack Compute API v2
<http://docs.openstack.org/api/openstack-compute/2/content>`_.
10

11
This document's goals are:
12

13
14
15
* Define the Cyclades/Compute ReST API
* Clarify the differences between Cyclades and OOS Compute

16
17
18
19
Users and developers who wish to access a synnefo Cyclades service through its
ReST API are adviced to use the `kamaki <http://docs.dev.grnet.gr/kamaki>`_
command-line client and associated python library, instead of making direct
calls.
20
21
22
23

Overview
========

24
25
26
27
* It is not defined if requests for invalid URLs should return 404 or a Fault.
  We return a BadRequest Fault.
* It is not defined if requests with a wrong HTTP method should return 405 or a
  Fault. We return a BadRequest Fault.
28
29
30
31
32
33
34
35
36
37
38
39
40
41


General API Information
=======================

Authentication
--------------

* Authentication support is missing.


Request/Response Types
----------------------

42
43
* We only support JSON Requests and JSON/XML Responses. XML Requests are not
  supported for now.
44
45
46
47
48
49
50
51
52
53
54


Content Compression
-------------------

* Optional content compression support is missing.


Persistent Connections
----------------------

55
56
* Deployment note: "To prevent abuse, HTTP sessions have a timeout of 20
  seconds before being closed."
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86


Links and References
--------------------

* Full URI references support is missing.
* Self and bookmark links support is missing.


Paginated Collections
---------------------

* Pagination support is missing.


Caching
-------

* We do not return cached responses.


Limits
------

 * Limits support is missing.


Efficient Polling with the Changes-Since Parameter
--------------------------------------------------

87
88
* Effectively limit support of the changes-since parameter in **List Servers**
and **List Images**.
89
90
* Assume that garbage collection of deleted servers will only affect servers
  deleted ``POLL_TIME`` seconds in the past or earlier. Else loose the
91
  information of a server getting deleted.
92
* Images do not support a deleted state, so deletions cannot be tracked.
93
94
95
96
97
98
99


Versions
--------

* Version MIME type support is missing.
* Versionless requests are not supported.
100
* We hardcode the ``updated`` field in versions list
101
* Deployment note: The Atom metadata needs to be fixed
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119


Extensions
----------

* Extensions support is missing.


Faults
------


API Operations
==============

Servers
-------

120
121
122
123
* ``hostId`` is always empty.
* ``affinityId`` is not returned.
* ``progress`` is always returned.
* ``self`` and ``bookmark`` atom links are not returned.
124
125
126
127
128
129
* **Get Server Details** will also return servers with a DELETED state.
* **Create Server** does not support setting the password in the request.

List Servers
............

130
131
132
133
134
135
136
=================== ====== ======== ==========
URI                 Method Cyclades OS Compute
=================== ====== ======== ==========
``/servers``        GET    ✔        ✔
``/servers/detail``
=================== ====== ======== ==========

137
138
* Both requests return a list of servers. The first returns just ``id`` and
``name``, while the second returns the full set of server attributes.
139
140
141
142

================= =================================== ======== ==========
Request Parameter Value                               Cyclades OS Compute
================= =================================== ======== ==========
143
144
json              Respond in json                     default  **✘**
xml               Respond in xml                      ✔        **✘**
145
146
147
148
149
150
151
152
153
changes-since     Servers delete since that timestamp ✔        ✔
image             Image reference                     **✘**    ✔
flavor            VM flavor reference                 **✘**    ✔
server            Server flavor reference             **✘**    ✔
status            Server status                       **✘**    ✔
marker            Last list last ID                   **✘**    ✔
limit             Page size                           **✘**    ✔
================= =================================== ======== ==========

154
155
* **json** and **xml** parameters are mutually exclusive. If none supported,
the response will be formated in json.
156

157
158
* **status** refers to the `server status <#status-ref>`_

159
160
* **changes-since** must be an ISO8601 date string

161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
304 (No servers since date) Can be returned if ``changes-since`` is given
400 (Bad Request)           Invalid or malformed ``changes-since`` parameter
401 (Unauthorized)          Missing or expired user token
178
403 (Forbidden)             User is not allowed to perform this operation
179
180
500 (Internal Server Error) The request cannot be completed because of an
internal error
181
182
183
184
503 (Service Unavailable)   The server is not currently available
=========================== =====================


185
186
The response data format is a list of servers under the ``servers`` label. A
server may have the fields presented bellow:
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

================= ====================== ======== ==========
Server Attributes Description            Cyclades OS Compute
================= ====================== ======== ==========
id                The server id          ✔        ✔
name              The server name        ✔        ✔
hostId            Server playground      empty    ✔
created           Creation date          ✔        ✔
updated           Creation date          ✔        ✔
flavorRef         The flavor id          ✔        **✘**
flavor            The flavor id          **✘**    ✔
imageRef          The image id           ✔        **✘**
image             The image id           **✘**    ✔
progress          Build progress         ✔        ✔
status            Server status          ✔        ✔
attachments       Network interfaces     ✔        **✘**
addresses         Network interfaces     **✘**    ✔
metadata          Server custom metadata ✔        ✔
================= ====================== ======== ==========
206
207
208
209

* **hostId** is not used in Cyclades, but is returned as an empty string for compatibility


210
211
* **progress** is changing while the server is building up and has values
between 0 and 100. When it reaches 100 the server is built.
212
213


214
* **status** refers to `the status <#status-ref>`_ of the server
215

216
217
* **metadata** are custom key:value pairs used to specify various attributes of
the VM (e.g. OS, super user, etc.)
218
219


220
221
222
223
224
225
226
* **attachments** in Cyclades are lists of network interfaces (nics).
**Attachments** are different to OS Compute's **addresses**. The former is a
list of the server's `network interface connections <#nic-ref>`_ while the
later is just a list of networks. Thus, a Cyclades virtual server may be
connected to the same network through more than one distinct network interfaces
(e.g. server 43 is connected to network 101 with nic-43-1 and nic-43-2 in the
example bellow).
227

228
229
230
231
232
* **Network Interfaces (NICs)** contain information about a server's connection
to a network. Each nic is identified by an id of the form
nic-<server-id>-<ordinal-number> and may contain a ``network_id``, a
``mac_address``, ``ipv4`` and ``ipv6`` addresses and the ``firewallProfile`` of
the connection.
233

234
235
236
**Example List Servers: JSON**

.. code-block:: javascript
237
238
239
240
241

  {
      'servers':
          {'values': [
              {
242
                  'attachments': {'values': [
243
                          {
244
245
246
247
248
249
                              'id': 'nic-42-0',
                              'network_id': '101',
                              'mac_address': 'aa:00:00:49:2e:7e',
                              'firewallProfile': DISABLED,
                              'ipv4': '192.168.4.5',
                              'ipv6': '2001:648:2ffc:1222:a800:ff:fef5:3f5b'
250
251
252
253
254
                          }
                  ]},
                  'created': '2011-04-19T10:18:52.085737+00:00',
                  'flavorRef': 1,
                  'hostId': '',
255
                  'id': 42,
256
257
258
259
260
261
262
                  'imageRef': 3,
                  'metadata': {'values': {'foo': 'bar'}},
                  'name': 'My Server',
                  'status': 'ACTIVE',
                  'updated': u'2011-05-29T14:07:07.037602+00:00'
              },
              {
263
                  'attachments': {'values': [
264
                          {
265
                              'id': 'nic-43-0',
266
                              'mac': 'aa:00:00:91:2f:df',
267
268
                              'network_id': '1',
                              'ipv4': '192.168.32.2'
269
270
                          },
                          {
271
272
273
274
275
276
                              'id': 'nic-43-1',
                              'network_id': '101',
                              'mac_address': 'aa:00:00:49:2g:7f',
                              'firewallProfile': DISABLED,
                              'ipv4': '192.168.32.6',
                              'ipv6': '2001:648:2ffc:1222:a800:ff:fef5:3f5c'
277
                          },
278
279
280
281
282
283
284
285
                          {
                              'id': 'nic-43-2',
                              'network_id': '101',
                              'mac_address': 'aa:00:00:51:2h:7f',
                              'firewallProfile': DISABLED,
                              'ipv4': '192.168.32.7',
                              'ipv6': '2001:638:2eec:1222:a800:ff:fef5:3f5c'
                          }
286
287
288
289
                  ]},
                  'created': '2011-05-02T20:51:08.527759+00:00',
                  'flavorRef': 1,
                  'hostId': '',
290
                  'id': 43,
291
292
                  'imageRef': 3,
                  'name': 'Other Server',
293
                  'description': 'A sample server to showcase server requests',
294
295
296
297
298
299
300
301
302
                  'progress': 0,
                  'status': 'ACTIVE',
                  'updated': '2011-05-29T14:59:11.267087+00:00'
              }
          ]
      }
  }


303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
Create Server
.............

=================== ====== ======== ==========
URI                 Method Cyclades OS Compute
=================== ====== ======== ==========
``/servers``        POST   ✔        ✔
=================== ====== ======== ==========

|

================= ===============
Request Parameter Value          
================= ===============
json              Respond in json
xml               Respond in xml 
================= ===============

|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

329
330
The request body is json formated. It consists of a ``server`` tag over the
following attributes:
331
332
333
334
335
336
337
338
339
340
341
342
343

=========== ==================== ======== ==========
Name        Description          Cyclades OS Compute
=========== ==================== ======== ==========
name        The server name      ✔        ✔
imageRef    Image id             ✔        ✔
flavorRef   Resources flavor     ✔        ✔
personality Personality contents ✔        ✔
metadata    Custom metadata      ✔        ✔
=========== ==================== ======== ==========

* **name** can be any string

344
345
* **imageRed** and **flavorRed** should refer to existing images and hardware
flavors accessible by the user
346

347
348
* **metadata** are key:value pairs of custom server-specific metadata. There
are no semantic limitations.
349

350
351
352
* **personality** (optional) is a list of personality injections. A personality injection is a small set of changes to a virtual server. Each change modifies a
file on the virtual server, by injecting some data in it. The injected data
(``content``) should exceed 10240 *bytes* in size and must be base64 encoded. A personality injection contains the following attributes:
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373

======== =================== ======== ==========
Name     Description         Cyclades OS Compute
======== =================== ======== ==========
path     File path on server ✔        ✔
contents Data to inject      ✔        ✔
group    User group          ✔        **✘**
mode     File access mode    ✔        **✘**
owner    File owner          ✔        **✘**
======== =================== ======== ==========

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed request data
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             User is not allowed to perform this operation
404 (Not Found)             Image or Flavor not found
374
375
413 (Over Limit)            Exceeded some resource limit (#VMs, personality
size, etc.) 
376
415 (Bad Media Type)        
377
378
379
380
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   No available backends or service currently
unavailable
381
382
383
384
=========================== =====================

|

385
386
In case of a 200 return code, the Response Data are json-formated and consist
of a `list of attributes <#server-ref>`_ under the ``server`` tag:
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403

For example::

  {"server": {
    "id": 28130
    "status": "BUILD",
    "updated": "2013-04-10T13:52:18.140686+00:00",
    "hostId": "",
    "name": "My Server Name: Example Name",
    "imageRef": "da7a211f-1db5-444a-938b-f901ce81a3e6",
    "created": "2013-04-10T13:52:17.085402+00:00",
    "flavorRef": 289,
    "adminPass": "fKCqlZe2at",
    "suspended": false,
    "progress": 0,
  }}

404
405
406
Get Server Stats
................

407
408
This operation returns URLs to graphs showing CPU and Network statistics. A
``refresh`` attribute is returned as well that is the recommended refresh rate
409
410
411
of the stats for the clients.

.. note:: This operation is not included in OS Compute v2.
412

413
414
415
416
417
============================== ====== ======== ==========
URI                            Method Cyclades OS Compute
============================== ====== ======== ==========
``/servers/<server-id>/stats`` GET    ✔        **✘**
============================== ====== ======== ==========
418

419
* **server-id** is the identifier of the virtual server
420

421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

================= ===============
Request Parameter Value          
================= ===============
json              Respond in json
xml               Respond in xml 
================= ===============

438
439
* **json** and **xml** parameters are mutually exclusive. If none supported,
the response will be formated in json.
440
441
442
443
444
445
446
447
448
449
450

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Server deleted
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
451
452
500 (Internal Server Error) The request cannot be completed because of an
internal error
453
454
455
456
503 (Service Unavailable)   The server is not currently available
=========================== =====================

|
457

458
459
460
461
462
463
464
465
466
467
================== ======================
Response Parameter Description           
================== ======================
serverRef          Server ID
refresh            Refresh frequency
cpuBar             Latest CPU load graph URL
cpuTimeSeries      CPU load / time graph URL
netBar             Latest Network load graph URL
netTimeSeries      Network load / time graph URL
================== ======================
468

469
470
471
**Example Get Server Stats Response: JSON**:

.. code-block:: javascript
472
473
474
475
476
477
478
479
480
481
482
483

  {
      "stats": {
          "serverRef": 1,
          "refresh": 60,
          "cpuBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png",
          "cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png",
          "netBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png",
          "netTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png"
      }
  }

484
485
486
**Example Get Network Details Response: XML**:

.. code-block:: xml
487
488

  <?xml version="1.0" encoding="UTF-8"?>
489
  <stats xmlns="http://docs.openstack.org/compute/api/v1.1"\
490
491
492
493
494
495
496
    xmlns:atom="http://www.w3.org/2005/Atom"
    serverRef="1"
    refresh="60"
    cpuBar="https://www.example.com/stats/snf-42/cpu-bar/",
    netTimeSeries="https://example.com/stats/snf-42/net-ts/",
    netBar="https://example.com/stats/snf-42/net-bar/",
    cpuTimeSeries="https://www.example.com/stats/snf-42/cpu-ts/"
497
498
  </stats>

499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
Get Server Diagnostics
......................

This operation returns diagnostic information for a server.

.. note:: This operation is not included in OS Compute v2.

==================================== ====== ======== ==========
URI                            Method Cyclades OS Compute
==================================== ====== ======== ==========
``/servers/<server-id>/diagnostics`` GET    ✔        **✘**
==================================== ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Server deleted
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   The server is not currently available
=========================== =====================

If a 200 code is returned, the response body contains a list of items. Each
item is a diagnostic entry and consists of the attributes presented bellow:

==================== ===========
Diagnostic attribute Description
==================== ===========
level                Debug level
created              Log entry timestamp
source               Log source proccess
source_date          Log source date          
message              Log description
details              Detailed log description
==================== ===========

For example:

.. code-block:: javascript

  [
    {
      "level": "DEBUG",
      "created": "2013-04-09T15:25:53.965144+00:00",
      "source": "image-helper-task-start",
      "source_date": "2013-04-09T15:25:53.954695+00:00",
      "message": "FixPartitionTable",
      "details": null
    }, {
      "level": "DEBUG",
      "created": "2013-04-09T15:25:46.413718+00:00",
      "source": "image-info",
      "source_date": "2013-04-09T15:25:46.404477+00:00",
      "message": "Starting customization VM...",
      "details": null
    }, {
      "level": "DEBUG",
      "created": "2013-04-09T15:25:46.207038+00:00",
      "source": "image-info",
      "source_date": "2013-04-09T15:25:46.197183+00:00",
      "message": "Image copy finished.",
      "details": "All operations finished as they should. No errors reported."
    }
  ]

580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
Get Server Details
..................

======================== ====== ======== ==========
URI                      Method Cyclades OS Compute
======================== ====== ======== ==========
``/servers/<server id>`` GET    ✔        ✔
======================== ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
609
610
611
612
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   No available backends or service currently
unavailable
613
614
615
616
=========================== =====================

|

617
618
The response data format is a list of servers under the ``servers`` label. A
server may have the fields presented bellow:
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633

================= ====================== ======== ==========
Server Attributes Description            Cyclades OS Compute
================= ====================== ======== ==========
id                The server id          ✔        ✔
name              The server name        ✔        ✔
hostId            Server playground      empty    ✔
created           Creation date          ✔        ✔
updated           Creation date          ✔        ✔
flavorRef         The flavor id          ✔        **✘**
flavor            The flavor id          **✘**    ✔
imageRef          The image id           ✔        **✘**
image             The image id           **✘**    ✔
progress          Build progress         ✔        ✔
status            Server status          ✔        ✔
634
suspended         If server is suspended ✔        **✘**
635
636
637
attachments       Network interfaces     ✔        **✘**
addresses         Network interfaces     **✘**    ✔
metadata          Server custom metadata ✔        ✔
638
diagnostics       Diagnostic information ✔        **✘**
639
640
641
642
643
644
================= ====================== ======== ==========

|

* **hostId** is not used in Cyclades, but is returned as an empty string for compatibility

645
646
* **progress** is changing while the server is building up and has values
between 0 and 100. When it reaches 100 the server is built.
647
648
649

* **status** refers to `the status <#status_ref>`_ of the server

650
651
* **metadata** are custom key:value pairs used to specify various attributes of
the VM (e.g. OS, super user, etc.)
652

653
654
655
656
657
658
* **attachments** in Cyclades are lists of network interfaces (NICs).
**Attachments** are different to OS Compute's **addresses**. The former is a
list of the server's `network interface connections <#nic-ref>`_ while the
later is just a list of networks. Thus, a Cyclades virtual server may be
connected to the same network through more than one distinct network
interfaces.
659

660
661
662
* **diagnostics** is a list of items that contain key:value information useful
for diagnosing the server behavior and may be used by the administrators of
deployed Synnefo setups.
663

664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
**Example Details for server with id 42042, in JSON**

.. code-block:: javascript

  {
    "server": {
      "id": 42042,
      "name": "My Example Server",
      "status": "ACTIVE",
      "updated": "2013-04-18T10:09:57.824266+00:00",
      "hostId": "",
      "imageRef": "926a1bc5-2d85-49d4-aebe-0fc127ed89b9",
      "created": "2013-04-18T10:06:58.288273+00:00",
      "flavorRef": 22,
      "attachments": {
        "values": [{
          "network_id": "1888",
          "mac_address": "aa:0c:f5:ad:16:41",
          "firewallProfile": "DISABLED",
          "ipv4": "83.212.112.56",
          "ipv6": "2001:648:2ffc:1119:a80c:f5ff:fead:1641",
          "id": "nic-42042-0"
        }]
      },
      "suspended": false,
      "diagnostics": [{
        "level": "DEBUG",
        "created": "2013-04-18T10:09:52.776920+00:00",
        "source": "image-info",
        "source_date": "2013-04-18T10:09:52.709791+00:00",
        "message": "Image customization finished successfully.",
        "details": null
      }],
      "progress": 100,
      "metadata": {
        "values": {"OS": "windows", "users": "Administrator"}
      }
    }
  }
703

704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
Rename Server
.............

======================== ====== ======== ==========
URI                      Method Cyclades OS Compute
======================== ====== ======== ==========
``/servers/<server id>`` PUT    ✔        ✔
======================== ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

723
724
The request body is json formated. It consists of a ``server`` tag over the
following attributes:
725
726
727
728
729
730
731
732
733

=========== ==================== ======== ==========
Name        Description          Cyclades OS Compute
=========== ==================== ======== ==========
name        The server name      ✔        ✔
accessIPv4  IP v4 address        **✘**    ✔
accessIPv6  IP v6 address        **✘**    ✔
=========== ==================== ======== ==========

734
735
* In Cyclades, a virtual server may use multiple network connections, instead
of limit them to one.
736
737
738
739
740
741
742
743
744
745
746
747
748

|

=========================== =====================
Return Code                 Description
=========================== =====================
204 (OK)                    Request succeeded
400 (Bad Request)           Malformed request or malformed server id
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             User is not allowed to perform this operation
404 (Not Found)             Server not found
415 (Bad Media Type)
409 (Build In Progress)     Server is not ready yet
749
750
751
752
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   No available backends or service currently
unavailable
753
754
=========================== =====================

755
756
757
In case of a 204 return code, there will be no request results according to the
Cyclades API, while the new server details are returned according to OS Compute
API.
758

759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
Delete Server
.............

======================== ====== ======== ==========
URI                      Method Cyclades OS Compute
======================== ====== ======== ==========
``/servers/<server id>`` DELETE ✔        ✔
======================== ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

|

=========================== =====================
Return Code                 Description
=========================== =====================
204 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id or machine already deleted
401 (Unauthorized)          Missing or expired user token
404 (Not Found)             Server not found
409 (Build In Progress)     Server is not ready yet
788
789
790
791
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   Action not supported or service currently
unavailable
792
793
=========================== =====================

794
795
796
Server Addresses
----------------

797
List Addresses
798
..............
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836

List all network connections of a server

============================ ====== ======== ==========
URI                          Method Cyclades OS Compute
============================ ====== ======== ==========
``/servers/<server id>/ips`` GET    ✔        ✔
============================ ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

|

================= ===============
Request Parameter Value          
================= ===============
json              Respond in json
xml               Respond in xml 
================= ===============

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id or machine already deleted
401 (Unauthorized)          Missing or expired user token
404 (Not Found)             Server not found
409 (Build In Progress)     Server is not ready yet
837
838
500 (Internal Server Error) The request cannot be completed because of an
internal error
839
840
841
503 (Service Unavailable)   Service currently unavailable
=========================== =====================

842
843
If the return code is 200, the response body consists of a list of items under
the ``addresses`` tag. Each item refers to a network interface connection (NIC).
844

845
846
847
848
849
850
851
Each NIC connects the current server to a network. NICs are different to OS
Compute's addresses. The formers are the server's
`network interface connections <#nic-ref>`_ while the later describes a network. Cyclades API suggests this information can be acquired by the network_id, using
the network part of the API. Thus, a Cyclades virtual server may be connected
to the same network through more than one distinct network interfaces. The NIC
mechanism allows more metadata to describe the network and its relation to the
server.
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878

**An example of a response, in JSON**

.. code-block:: javascript

  {
    "addresses": {
      "values": [
          {
            "network_id": "1",
            "mac_address": "aa:00:03:7a:84:bb",
            "firewallProfile": "DISABLED",
            "ipv4": "192.168.0.27",
            "ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb",
            "id": "nic-25455-0"
          }, {
            "network_id": "7",
            "mac_address": "aa:00:03:7a:84:cc",
            "firewallProfile": "DISABLED",
            "ipv4": "192.168.0.28",
            "ipv6": "2002:646:2fec:1222:a820:3fd:fe7a:84bc",
            "id": "nic-25455-1"
          },
      ]
    }
  }

879
Get Server NIC by Network
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
.........................

Return the NIC that connects a server to a network

========================================= ====== ======== ==========
URI                                       Method Cyclades OS Compute
========================================= ====== ======== ==========
``/servers/<server id>/ips/<network id>`` GET    ✔        ✔
========================================= ====== ======== ==========

* **server-id** is the identifier of the virtual server

* **network-id** is the identifier of the virtual server

|

==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

|

================= ===============
Request Parameter Value          
================= ===============
json              Respond in json
xml               Respond in xml 
================= ===============

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id or machine already deleted
401 (Unauthorized)          Missing or expired user token
404 (Not Found)             Server not found
409 (Build In Progress)     Server is not ready yet
921
922
500 (Internal Server Error) The request cannot be completed because of an
internal error
923
924
925
503 (Service Unavailable)   Service currently unavailable
=========================== =====================

926
927
If the return code is 200, the response body consists of a NIC under the
``network`` tag.
928

929
930
931
This NIC (`network interface connections <#nic-ref>`_) connects the specified
server to the specified network. NICs are only used in Cyclades API. The same
operation in OS Compute API returns a list of IP addresses.
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947

**An example of a response, in JSON**

.. code-block:: javascript

  {
    "network": {
        "network_id": "7",
        "mac_address": "aa:00:03:7a:84:bb",
        "firewallProfile": "DISABLED",
        "ipv4": "192.168.0.27",
        "ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb",
        "id": "nic-25455-0"
    }
  }

948
949
950
Server Actions
--------------

951
952
953
954
955
The request described in this section exists in both Synnefo API and OS Compute
API as a multi-operation request. The individual operations implemented through
this request are in many cases completely different between the two APIs.
Although this document focuses on Synnefo operations, differences and
similarities between the APIs are also briefed in this section.
956

957
|
958

959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
============================= ======== ==========
Operations                    Cyclades OS Compute
============================= ======== ==========
Start Server                  ✔        **✘**
Shutdown Server               ✔        **✘**
Reboot Server                 ✔        ✔
Get Server Console            ✔        **✘**
Set Firewall Profile          ✔        **✘**
Change Administrator Password **✘**    ✔
Rebuild Server                **✘**    ✔
Resize Server                 **✘**    ✔
Confirm Resized Server        **✘**    ✔
Revert Resized Server         **✘**    ✔
Create Image                  **✘**    ✔
============================= ======== ==========
974

975
|
976

977
978
979
980
981
====================================== ====== ======== ==========
URI                                    Method Cyclades OS Compute
====================================== ====== ======== ==========
``/servers/<server id>/action``        POST   ✔        ✔
====================================== ====== ======== ==========
982

983
|
984

985
986
987
988
989
==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========
990

991
|
992

993
994
995
996
997
998
999
1000
=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded (for console operation)
202 (OK)                    Request succeeded
400 (Bad Request)           Invalid request or unknown action
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             User is not allowed to perform this operation
1001
1002
500 (Internal Server Error) The request cannot be completed because of an
internal error
1003
1004
503 (Service Unavailable)   The server is not currently available
=========================== =====================
1005

1006
1007
Start server
................
1008

1009
This operation transitions a server from a STOPPED to an ACTIVE state.
1010

1011
Request body must contain a ``start`` tag on an empty directory::
1012

1013
  { 'start': {}}
1014
1015


1016
1017
Reboot Server
.............
1018

1019
1020
1021
1022
1023
This operation transitions a server from ``ACTIVE`` to ``REBOOT`` and then
``ACTIVE`` again. Synnefo and OS Compute APIs offer two reboot modes: soft and
hard. The only difference is that OS Compute distinguishes between the two
types of intermediate states (``REBOOT`` and ``HARD_REBOOT``) while rebooting,
but the expected behavior is the same in both APIs.
1024

1025
1026
Request body must contain a ``reboot`` tag over a ``type`` tag on the reboot
type::
1027

1028
1029
1030
  { 'reboot' : { 'type': <reboot type>}}

* **reboot type** can be either ``SOFT`` or ``HARD``.
1031

1032
1033
1034
1035
** Reboot Action Request Body Example: JSON **

.. code-block:: javascript
  
1036
  {
1037
1038
1039
    'reboot': {
      'type': 'hard'
      }
1040
1041
  }

1042
1043
1044
1045
1046
1047
Shutdown server
...............

This operation transitions a server from an ACTIVE to a STOPPED state.

Request body must contain a ``shutdown`` tag on an empty directory::
1048

1049
  { 'shutdown': {}}
1050
1051

Get Server Console
1052
..................
1053

1054
1055
1056
1057
The console operation arranges for an OOB console of the specified type. Only
consoles of type "vnc" are supported for now. Cyclades server 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.
1058

1059
1060
Request body must a contain a ``console`` tag over a ``type`` tag on a console
type::
1061

1062
  console: {type: 'vnc' }
1063

1064
1065
If successful, it returns a **200** code and also a json formated body with the
following fields:
1066

1067
1068
1069
1070
1071
1072
1073
1074
================== ======================
Response Parameter Description           
================== ======================
host               The vncprocy host
port               vncprocy port
password           Temporary password
type               Connection type (only VNC)
================== ======================
1075

1076
|
1077

1078
1079
1080
**Example Action Console Response: JSON**:

.. code-block:: javascript
1081
1082
1083
1084

  {
      "console": {
          "type": "vnc",
1085
          "host": "vm42.example.org",
1086
          "port": 1234,
1087
          "password": "513NR4PN0T"
1088
1089
1090
      }
  }

1091
1092
1093
**Example Action Console Response: XML**:

.. code-block:: xml
1094
1095

  <?xml version="1.0" encoding="UTF-8"?>
1096
1097
  <console xmlns="http://docs.openstack.org/compute/api/v1.1"
      xmlns:atom="http://www.w3.org/2005/Atom"
1098
      type="vnc"
1099
      host="vm42.example.org"
1100
      port="1234"
1101
      password="513NR4PN0T">
1102
1103
1104
1105
1106
  </console>

Set Firewall Profile
....................

1107
1108
The firewallProfile function sets a firewall profile for the public interface
of a server.
1109

1110
1111
Request body must contain a ``firewallProfile`` tag over a ``profile`` tag on
the firewall type::
1112

1113
  firewallProfile: { profile: <firewall profile> }
1114

1115
* **firewall profile** can be ``ENABLED``, ``DISABLED`` or ``PROTECTED``
1116

1117
1118
1119
**Example Action firewallProfile: JSON**:

.. code-block:: javascript
1120
1121
1122
1123
1124
1125
1126

  {
      "firewallProfile": {
          "profile": "ENABLED"
      }
  }

1127
1128
1129
1130
1131
1132
1133
1134
1135
1136

OS Compute API Specific
.......................

* `Change Administrator Password <http://docs.openstack.org/api/openstack-compute/2/content/Change_Password-d1e3234.html>`_
* `Rebuild Server <http://docs.openstack.org/api/openstack-compute/2/content/Rebuild_Server-d1e3538.html>`_
* `Resize Server <http://docs.openstack.org/api/openstack-compute/2/content/Resize_Server-d1e3707.html>`_
* `Confirm Resized Server <http://docs.openstack.org/api/openstack-compute/2/content/Confirm_Resized_Server-d1e3868.html>`_
* `Revert Resized Server <http://docs.openstack.org/api/openstack-compute/2/content/Revert_Resized_Server-d1e4024.html>`_
* `Create Image <http://docs.openstack.org/api/openstack-compute/2/content/Create_Image-d1e4655.html>`_
1137
1138


1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
Server Metadata
---------------

List metadata
.............

.. note:: This operation is semantically equivalent in Cyclades and OS Compute.

================================= ====== ======== ==========
URI                               Method Cyclades OS Compute
================================= ====== ======== ==========
``/servers/<server-id>/meta``     GET    ✔        **✘**
``/servers/<server-id>/metadata`` GET    **✘**    ✔
================================= ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Malformed request
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   The server is not currently available
=========================== =====================

In case of a 200 response code, the response should contain a JSON encoded list
of key:value pairs, under a 'values' tag which lies under a ``metadata`` tag,
for example::

  { 
    'metadata': {
      'values': {
        'OS': 'Linux',
        'users': 'root'
      }
    }
  }

.. note:: In OS Compute API  the 'values' level is missing from the response

Set / Update Server Metadata
............................

In Cyclades API, setting new metadata and updating the values of existing ones
is achieved with the same type of request (POST), while in OS Compute API there
are two separate request types (PUT and POST for
`setting new <http://docs.openstack.org/api/openstack-compute/2/content/Create_or_Replace_Metadata-d1e5358.html>`_
and
`updating existing <http://docs.openstack.org/api/openstack-compute/2/content/Update_Metadata-d1e5208.html>`_
metadata, respectively).

In Cyclades API, metadata keys not referred by the operation will
remain intact, while metadata referred by the operation will be overwritten in
case of success.

================================= ====== ======== ==========
URI                               Method Cyclades OS Compute
================================= ====== ======== ==========
``/servers/<server-id>/meta``     POST    ✔        **✘**
``/servers/<server-id>/metadata`` PUT    **✘**    ✔
``/servers/<server-id>/metadata`` POST    **✘**   ✔
================================= ====== ======== ==========

* **server-id** is the identifier of the virtual server

|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

The request body should contain a JSON-formated set of key:value pairs, under
the ``metadata`` tag, e.g.::

  {'metadata': {'role': 'webmail', 'users': 'root,maild'}}

|

=========================== =====================
Return Code                 Description
=========================== =====================
201 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Malformed request
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
413 (OverLimit)             Maximum number of metadata exceeded
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   The server is not currently available
=========================== =====================

|

In case of a 201 code, the response body should present the new state of
servers metadata. E.g.::

  {'metadata': {'OS': 'Linux', 'role': 'webmail', 'users': 'root,maild'}}

Get Metadata Item
.................

.. note:: This operation is semantically equivalent in Cyclades and OS Compute.

======================================= ====== ======== ==========
URI                                     Method Cyclades OS Compute
======================================= ====== ======== ==========
``/servers/<server-id>/meta/<key>``     GET    ✔        **✘**
``/servers/<server-id>/metadata/<key>`` GET    **✘**    ✔
======================================= ====== ======== ==========

* **server-id** is the identifier of the virtual server
* **key** is the key of a matadatum key:value pair

|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Malformed request
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Metadatum key not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   The server is not currently available
=========================== =====================

If the response code is 200, the response body contains the requested key:value
pair under a ``metadata`` tag. For example, if key was ``role``, the response
body would look similar to this::

  {'metadata': {'role': 'webmail'}}

.. note:: In OS Compute response, ``metadata`` is ``meta``

Set / Update Metadatum Item
...........................

.. note:: This operation is semantically equivalent in Cyclades and OS Compute.

======================================= ====== ======== ==========
URI                                     Method Cyclades OS Compute
======================================= ====== ======== ==========
``/servers/<server-id>/meta/<key>``     PUT    ✔        **✘**
``/servers/<server-id>/metadata/<key>`` PUT    **✘**    ✔
======================================= ====== ======== ==========

* **server-id** is the identifier of the virtual server
* **key** is the key of a matadatum key:value pair

|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

Request body should contain a ``key``:``value`` pair under a ``meta`` tag.
The ``value`` is the (new) value to set. The ``key`` of the metadatum may or
may not exist prior to the operation. For example, request with ``role`` as a
``key`` may contain the following request body::

  {'meta': {'role': 'gateway'}}

|

=========================== =====================
Return Code                 Description
=========================== =====================
201 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Malformed request
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Metadatum key not found
413 (OverLimit)             Maximum number of metadata exceeded
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   The server is not currently available
=========================== =====================

|

If the response code is 201, the response body contains the ``key:pair``
that has just been created or updated, under a ``meta`` tag, so that the body
of the response is identical to the body of the request.

Delete Server metadata
......................

.. note:: This operation is semantically equivalent in Cyclades and OS Compute.

======================================= ====== ======== ==========
URI                                     Method Cyclades OS Compute
======================================= ====== ======== ==========
``/servers/<server-id>/meta/<key>``     DELETE ✔        **✘**
``/servers/<server-id>/metadata/<key>`` DELETE **✘**    ✔
======================================= ====== ======== ==========

* **server-id** is the identifier of the virtual server
* **key** is the key of a matadatum key:value pair

|

==============  =========================
Request Header  Value                    
==============  =========================
X-Auth-Token    User authentication token
==============  =========================

|

=========================== =====================
Return Code                 Description
=========================== =====================
204 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Metadatum key not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable)   The server is not currently available
=========================== =====================

1395

1396
1397
1398
Flavors
-------

1399
1400
* ``self`` and ``bookmark`` atom links are not returned.
* **List Flavors** returns just ``id`` and ``name`` if details is not requested.
1401
1402
1403
1404
1405


Images
------

1406
1407
1408
1409
1410
1411
* ``progress`` is always returned.
* ``self`` and ``bookmark`` atom links are not returned.
* **List Images** returns just ``id`` and ``name`` if details are not requested.
* **List Images** can return 304 (even though not explicitly stated) when
  ``changes-since`` is given. 
* **List Images** does not return deleted images when ``changes-since`` is given.
1412
1413
1414
1415
1416
1417
1418
1419



Networks
--------

This is an extension to the OpenStack API.

1420
1421
1422
1423
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.
1424

1425
1426
1427
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.
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438


List Networks
.............

**GET** /networks

**GET** /networks/detail

**Normal Response Codes**: 200, 203

1439
1440
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), badRequest (400), overLimit (413)
1441
1442
1443
1444
1445

This operation provides a list of private networks associated with your account.

This operation does not require a request body.

1446
1447
1448
**Example Networks List Response: JSON (detail)**:

.. code-block:: javascript
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474

  {
      "networks": {
          "values": [
              {
                  "id": "public",
                  "name": "public",
                  "created": "2011-04-20T15:31:08.199640+00:00",
                  "updated": "2011-05-06T12:47:05.582679+00:00",
                  "servers": {
                      "values": [1, 2, 3]
                  }
              },
              {
                  "id": 2,
                  "name": "private",
                  "created": "2011-04-20T14:32:08.199640+00:00",
                  "updated": "2011-05-06T11:40:05.582679+00:00",
                  "servers": {
                      "values": [1]
                  }
              }
          ]
      }
  }

1475
1476
1477
**Example Networks List Response: XML (detail)**:

.. code-block:: xml
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502

  <?xml version="1.0" encoding="UTF-8"?>
  <networks xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom">
    <network id="public" name="public" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00">
      <servers>
        <server id="1"></server>
        <server id="2"></server>
        <server id="3"></server>
      </servers>
    </network>
    <network id="2" name="private" updated="2011-05-06T12:47:05.582679+00:00" created="2011-04-20T15:31:33.911299+00:00">
      <servers>
        <server id="1"></server>
      </servers>
    </network>
  </networks>


Create Network
..............

**POST** /networks

**Normal Response Code**: 202

1503
1504
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), badMediaType(415), badRequest (400), overLimit (413)
1505
1506
1507

This operation asynchronously provisions a new private network.

1508
1509
1510
**Example Create Network Request: JSON**:

.. code-block:: javascript
1511
1512
1513
1514
1515
1516
1517

  {
      "network": {
          "name": "private_net",
      }
  }

1518
1519
1520
**Example Create Network Response: JSON**:

.. code-block:: javascript
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532

  {
      "network": {
          "id": 3,
          "name": "private_net",
          "created": "2011-04-20T15:31:08.199640+00:00",
          "servers": {
              "values": []
          }
      }
  }

1533
1534
1535
**Example Create Network Response: XML**:

.. code-block:: xml
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551

  <?xml version="1.0" encoding="UTF-8"?>
  <network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"
   id="2" name="foob" created="2011-04-20T15:31:08.199640+00:00">
    <servers>
    </servers>
  </network>


Get Network Details
...................

**GET** /networks/*id*

**Normal Response Codes**: 200, 203

1552
1553
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)
1554
1555
1556
1557
1558

This operation returns the details of a specific network by its id.

This operation does not require a request body.

1559
1560
1561
**Example Get Network Details Response: JSON**:

.. code-block:: javascript
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591

  {
      "network": {
          "id": 3,
          "name": "private_net",
          "servers": {
              "values": [1, 7]
          }
      }
  }

**Example Get Network Details Response: XML**::

  <?xml version="1.0" encoding="UTF-8"?>
  <network xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"
   id="2" name="foob" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00">
    <servers>
      <server id="1"></server>
      <server id="7"></server>
    </servers>
  </network>


Update Network Name
...................

**PUT** /networks/*id*

**Normal Response Code**: 204

1592
1593
1594
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),
overLimit (413) 
1595
1596
1597

This operation changes the name of the network in the Compute system.

1598
**Example Update Network Name Request: JSON**:
1599

1600
1601
.. code-block:: javascript

1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
  {
      "network": {
          "name": "new_name"
      }
  }

This operation does not contain a response body.


Delete Network
..............

**DELETE** /networks/*id*

**Normal Response Code**: 204

1618
1619
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), itemNotFound (404), unauthorized (401), overLimit (413) 
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635

This operation deletes a network from the system.

This operation does not require a request or a response body.


Network Actions
---------------

Add Server
..........

**POST** /networks/*id*/action

**Normal Response Code**: 202

1636
1637
1638
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),
overLimit (413)
1639
1640
1641

This operation adds a server to the specified network.

1642
1643
1644
**Example Action Add: JSON**:

.. code-block:: javascript
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661

  {
      "add" : {
          "serverRef" : 42
      }
  }

This operation does not contain a response body.


Remove Server
.............

**POST** /networks/*id*/action

**Normal Response Code**: 202

1662
1663
1664
**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),
unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),
overLimit (413)
1665
1666
1667

This operation removes a server from the specified network.

1668
1669
1670
**Example Action Remove: JSON**:

.. code-block:: javascript
1671
1672
1673
1674
1675
1676
1677
1678

  {
      "remove" : {
          "serverRef" : 42
      }
  }

This operation does not contain a response body.
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712

Index of details
----------------

.. _server-ref:

Server Attributes
.................

================ ========================== ======== ==========
Server attribute Description                Cyclades OS Compute
================ ========================== ======== ==========
id               Server ID                  ✔        ✔
name             Server Name                ✔        ✔
status           Server Status              ✔        ✔
updated          Date of last modification  ✔        ✔
created          Date of creation           ✔        ✔
hostId           Physical host              empty    ✔
imageRef         Image ID                   ✔        **✘**
image            A full image descreption   **✘**    ✔
flavorRef        Flavor ID                  ✔        **✘**
flavor           A full flavor description  **✘**    ✔
adminPass        Superuser Password         ✔        ✔
suspended        If server is suspended     ✔        ✔
progress         Build progress             ✔        ✔
metadata         Custom server metadata     ✔        ✔
user_id          Server owner               **✘**    ✔
tenant_id        Server tenant              **✘**    ✔
accessIPv4       Server IPV4 net address    **✘**    ✔
accessIPv6       Server IPV4 net address    **✘**    ✔
addresses        Nets connected on server   **✘**    ✔
links            Server links               **✘**    ✔
================ ========================== ======== ==========

1713
* **status** values are described `here <#status-ref>`_
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752

* **updated** and **created** are date-formated

* **hostId** is always empty in Cyclades and is returned for compatibility reasons

* **imageRef** and **flavorRef** always refer to existing Image and Flavor specifications. Cyclades improved the OpenStack approach by using references to Image and Flavor attributes, instead of listing their full properties

* **adminPass** in Cyclades it is generated automatically during creation. For safety, it is not stored anywhere in the system and it cannot be recovered with a query request

* **suspended** is True only of the server is suspended by the cloud administrations or policy

* **progress** is a number between 0 and 100 and reflects the server building status

* **metadata** are custom key:value pairs refering to the VM. In Cyclades, the ``OS`` and ``users`` metadata are automatically retrieved from the servers image during creation

.. _status-ref:

Server Status
.............

============= ==================== ======== ==========
Status        Description          Cyclades OS Compute
============= ==================== ======== ==========
BUILD         Building             ✔        ✔
ACTIVE        Up and running       ✔        ✔
STOPPED       Shut down            ✔        **✘**
REBOOT        Rebooting            ✔        ✔
DELETED       Removed              ✔        ✔
UNKNOWN       Unexpected error     ✔        ✔
ERROR         In error             ✔        ✔
HARD_REBOOT   Hard rebooting       **✘**    ✔
PASSWORD      Resetting password   **✘**    ✔
REBUILD       Rebuilding server    **✘**    ✔
RESCUE        In rescue mode       **✘**    ✔
RESIZE        Resizing             **✘**    ✔
REVERT_RESIZE Failed to resize     **✘**    ✔
SHUTOFF       Shut down by user    **✘**    ✔
SUSPENDED     Suspended            **✘**    ✔
VERIFY_RESIZE Waiting confirmation **✘**    ✔
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
============= ==================== ======== ==========

.. _nic-ref:

Network Interface Connection (NIC)
..................................

A Network Interface Connection (NIC) represents a servers connection to a network.

A NIC is identified by a server and an (obviously unique) mac address. A server can have multiple NICs, though. In practice, a NIC id is used of reference and identification.

Each NIC is used to connect a specific server to a network. The network is aware of that connection for as long as it holds. If a NIC is disconnected from a network, it is destroyed.

A NIC specification contains the following information:

================= ====================== ======== ==========
Server Attributes Description            Cyclades OS Compute
================= ====================== ======== ==========
id                The NIC id             ✔        **✘**
mac_address       NIC's mac address      ✔        **✘**
network_id        Network of connection  ✔        **✘**
firewallProfile   The firewall profile   ✔        **✘**
ipv4              IP v4 address          ✔        **✘**
ipv6              IP v6 address          ✔        **✘**
================= ====================== ======== ==========

* **id** is the unique identified of the NIC. It consists of the server id and an ordinal number nic-<server-id>-<ordinal number> , e.g. for a server with id 42::
  nic-42-0, nic-42-1, ...

* **mac_address** is the unique mac address of the interface

* **network_id** is the id of the network this nic connects to.

* **firewallProfile** , if set, refers to the mode of the firewall. Valid firewall profile values::

  ENABLED, DISABLED, PROTECTED

* **ipv4** and **ipv6** are the IP addresses (versions 4 and 6 respectively) of the specific network connection for that machine.