Statistics
| Branch: | Tag: | Revision:

root / docs / cyclades-api-guide.rst @ 534b3c29

History | View | Annotate | Download (108.5 kB)

1
.. _cyclades-api-guide:
2

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

    
6
`Cyclades <cyclades.html>`_ is the Compute Service of `Synnefo
7
<http://www.synnefo.org>`_. The Cyclades API tries to be as close to the
8
`OpenStack Compute API v2
9
<http://docs.openstack.org/api/openstack-compute/2/content>`_ as possible.
10

    
11
This document's goals are:
12

    
13
* Define the Cyclades/Compute REST API
14
* Clarify the differences between Cyclades and OpenStack/Compute
15

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

    
20
Overview
21
========
22

    
23
* OpenStack does not define if requests for invalid URLs should return 404 or a
24
* Fault. We return a BadRequest Fault.
25
* OpenStack does not define if requests with a wrong HTTP method should return
26
* 405 or a Fault. We return a BadRequest Fault.
27

    
28
General API Information
29
=======================
30

    
31
Authentication
32
--------------
33

    
34
All requests use the same authentication method: an ``X-Auth-Token`` header is
35
passed to the servive, which is used to authenticate the user and retrieve user
36
related information. No other user details are passed through HTTP.
37

    
38
Efficient Polling with the Changes-Since Parameter
39
--------------------------------------------------
40

    
41
* Effectively limit support of the changes-since parameter in **List Servers**
42
  and **List Images**.
43

    
44
* Assume that garbage collection of deleted servers will only affect servers
45
  deleted ``POLL_TIME`` seconds (default: 3600) in the past or earlier. Else
46
  loose the information of a server getting deleted.
47

    
48
* Images do not support a deleted state, so deletions cannot be tracked.
49

    
50
Limitations
51
-----------
52

    
53
* Version MIME type and vesionless requests are not currently supported.
54

    
55
* Cyclades only supports JSON Requests and JSON/XML Responses. XML Requests are
56
  currently not supported.
57

    
58
* Optional content compression support is currently not supported.
59

    
60
* To prevent abuse, HTTP sessions have a timeout of 20 seconds before being
61
  closed.
62

    
63
* Full URI references and ``self`` and ``bookmark`` links are not supported.
64

    
65
* Pagination is currently not supported.
66

    
67
* Cached responses are currently not supported.
68

    
69
* Limits are currently not supported.
70

    
71
* Extensions are currently not supported.
72

    
73

    
74
API Operations
75
==============
76

    
77
Servers
78
-------
79

    
80
=================================================== ========================================= ====== ======== ==========
81
Description                                         URI                                       Method Cyclades OS/Compute
82
=================================================== ========================================= ====== ======== ==========
83
`List <#list-servers>`_                             ``/servers``                              GET    ✔        ✔
84
\                                                   ``/servers/detail``                       GET    ✔        ✔
85
`Create <#create-server>`_                          ``/servers``                              POST   ✔        ✔
86
`Get Stats <#get-server-stats>`_                    ``/servers/<server-id>/stats``            GET    ✔        **✘**
87
`Get Diagnostics <#get-server-diagnostics>`_        ``/servers/<server-id>/diagnostics``      GET    ✔        **✘**
88
`Get Details <#get-server-details>`_                ``/servers/<server id>``                  GET    ✔        ✔
89
`Rename <#rename-server>`_                          ``/servers/<server id>``                  PUT    ✔        ✔
90
`Delete <#delete-server>`_                          ``/servers/<server id>``                  DELETE ✔        ✔
91
`List Addresses <#list-server-addresses>`_          ``/servers/<server id>/ips``              GET    ✔        ✔
92
`Get NICs by Net <#get-server-nics-by-network>`_    ``/servers/<server id>/ips/<network id>`` GET    ✔        ✔
93
`List Metadata <#list-server-metadata>`_            ``/servers/<server-id>/meta``             GET    ✔        **✘**
94
\                                                   ``/servers/<server-id>/metadata``         GET    **✘**    ✔
95
`Update Metadata <#set-update-server-metadata>`_    ``/servers/<server-id>/meta``             POST    ✔       **✘**
96
\                                                   ``/servers/<server-id>/metadata``         PUT    **✘**    ✔
97
\                                                   ``/servers/<server-id>/metadata``         POST   **✘**    ✔
98
`Get Meta Item <#get-server-metadata-item>`_        ``/servers/<server-id>/meta/<key>``       GET    ✔        **✘**
99
\                                                   ``/servers/<server-id>/metadata/<key>``   GET    **✘**    ✔
100
`Update Meta Item <#update-server-metadatum-item>`_ ``/servers/<server-id>/meta/<key>``       PUT    ✔        **✘**
101
\                                                   ``/servers/<server-id>/metadata/<key>``   PUT    **✘**    ✔
102
`Delete Meta Item <#delete-server-metadatum>`_      ``/servers/<server-id>/meta/<key>``       DELETE ✔        **✘**
103
\                                                   ``/servers/<server-id>/metadata/<key>``   DELETE **✘**    ✔
104
=================================================== ========================================= ====== ======== ==========
105

    
106
List Servers
107
............
108

    
109
List all virtual servers owned by the user.
110

    
111
.. rubric:: Request
112

    
113
=================== ====== ======== ==========
114
URI                 Method Cyclades OS/Compute
115
=================== ====== ======== ==========
116
``/servers``        GET    ✔        ✔
117
``/servers/detail`` GET    ✔        ✔
118
=================== ====== ======== ==========
119

    
120
* Both requests return a list of servers. The first returns just ``id`` and
121
  ``name``, while the second returns the full collections of server
122
  attributes.
123

    
124
|
125

    
126
==============  ========================= ======== ==========
127
Request Header  Value                     Cyclades OS/Compute
128
==============  ========================= ======== ==========
129
X-Auth-Token    User authentication token required required
130
==============  ========================= ======== ==========
131

    
132
|
133

    
134
================= =================================== ======== ==========
135
Request Parameter Value                               Cyclades OS/Compute
136
================= =================================== ======== ==========
137
json              Respond in json                     default  **✘**
138
xml               Respond in xml                      ✔        **✘**
139
changes-since     Servers delete since that timestamp ✔        ✔
140
image             Image reference                     **✘**    ✔
141
flavor            VM flavor reference                 **✘**    ✔
142
server            Server flavor reference             **✘**    ✔
143
status            Server status                       **✘**    ✔
144
marker            Last list last ID                   **✘**    ✔
145
limit             Page size                           **✘**    ✔
146
================= =================================== ======== ==========
147

    
148
* **json** and **xml** parameters are mutually exclusive. If none supported,
149
the response will be formated in json.
150

    
151
* **status** refers to the `server status <#status-ref>`_
152

    
153
* **changes-since** must be an ISO8601 date string
154

    
155
.. note:: Request body should be empty
156

    
157
.. rubric:: Response
158

    
159
=========================== =====================
160
Return Code                 Description
161
=========================== =====================
162
200 (OK)                    Request succeeded
163
304 (No servers since date) Can be returned if ``changes-since`` is given
164
400 (Bad Request)           Invalid or malformed ``changes-since`` parameter
165
401 (Unauthorized)          Missing or expired user token
166
403 (Forbidden)             User is not allowed to perform this operation
167
500 (Internal Server Error) The request cannot be completed because of an
168
\                           internal error
169
503 (Service Unavailable)   The server is not currently available
170
=========================== =====================
171

    
172
|
173

    
174
Response body contents::
175

    
176
  servers: [
177
    {
178
      <server attribute>: <value>,
179
      ...
180
    }, ...
181
  ]
182

    
183
================= ====================== ======== ==========
184
Server Attributes Description            Cyclades OS/Compute
185
================= ====================== ======== ==========
186
id                The server id          ✔        ✔
187
name              The server name        ✔        ✔
188
hostId            Server playground      empty    ✔
189
created           Creation date          ✔        ✔
190
updated           Creation date          ✔        ✔
191
flavorRef         The flavor id          ✔        **✘**
192
flavor            The flavor id          **✘**    ✔
193
imageRef          The image id           ✔        **✘**
194
image             The image id           **✘**    ✔
195
progress          Build progress         ✔        ✔
196
status            Server status          ✔        ✔
197
attachments       Network interfaces     ✔        **✘**
198
addresses         Network interfaces     **✘**    ✔
199
metadata          Server custom metadata ✔        ✔
200
================= ====================== ======== ==========
201

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

    
205
* **progress** is changing while the server is building up and has values
206
  between 0 and 100. When it reaches 100 the server is built.
207

    
208
* **status** refers to `the status <#status-ref>`_ of the server
209

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

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

    
221
* **Network Interfaces (NICs)** contain information about a server's connection
222
  to a network. Each NIC is identified by an id of the form
223
  nic-<server-id>-<ordinal-number>. More details can be found `here
224
  <#nic-ref>`_.
225

    
226
*Example List Servers: JSON*
227

    
228
.. code-block:: javascript
229

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

    
295

    
296
Create Server
297
.............
298

    
299
Create a new virtual server
300

    
301
.. rubric:: Request
302

    
303
============ ====== ======== ==========
304
URI          Method Cyclades OS/Compute
305
============ ====== ======== ==========
306
``/servers`` POST   ✔        ✔
307
============ ====== ======== ==========
308

    
309
|
310

    
311
==============  ========================= ======== ==========
312
Request Header  Value                     Cyclades OS/Compute
313
==============  ========================= ======== ==========
314
X-Auth-Token    User authentication token required required
315
Content-Type    Type or request body      required required
316
Content-Length  Length of request body    required required
317
==============  ========================= ======== ==========
318

    
319
*Example Request Headers*::
320

    
321
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
322
  Content-Type:   application/json
323
  Content-Length: 735
324

    
325
|
326

    
327
================= ===============
328
Request Parameter Value
329
================= ===============
330
json              Respond in json
331
xml               Respond in xml
332
================= ===============
333

    
334
Request body contents::
335

    
336
  server: {
337
      <server attribute>: <value>,
338
      ...
339
      personality: [
340
        {
341
          <personality attribute>: <value>,
342
          ...
343
        },
344
        ...
345
      ],
346
      ...
347
  }
348

    
349
=========== ==================== ======== ==========
350
Attributes  Description          Cyclades OS/Compute
351
=========== ==================== ======== ==========
352
name        The server name      ✔        ✔
353
imageRef    Image id             ✔        ✔
354
flavorRef   Resources flavor     ✔        ✔
355
personality Personality contents ✔        ✔
356
metadata    Custom metadata      ✔        ✔
357
=========== ==================== ======== ==========
358

    
359
* **name** can be any string
360

    
361
* **imageRed** and **flavorRed** should refer to existing images and hardware
362
  flavors accessible by the user
363

    
364
* **metadata** are ``key``:``value`` pairs of custom server-specific metadata.
365
  There are no semantic limitations.
366

    
367
* **personality** (optional) is a list of personality injections. A personality
368
  injection is a small set of changes to a virtual server. Each change modifies
369
  a file on the virtual server, by injecting some data in it. The injected data
370
  (``contents``) should exceed 10240 *bytes* in size and must be base64
371
  encoded. A personality injection contains the following attributes:
372

    
373
====================== =================== ======== ==========
374
Personality Attributes Description         Cyclades OS/Compute
375
====================== =================== ======== ==========
376
path                   File path on server ✔        ✔
377
contents               Data to inject      ✔        ✔
378
group                  User group          ✔        **✘**
379
mode                   File access mode    ✔        **✘**
380
owner                  File owner          ✔        **✘**
381
====================== =================== ======== ==========
382

    
383
*Example Create Server Request: JSON*
384

    
385
.. code-block:: javascript
386

    
387
  {
388
    "server": {
389
      "name": "My Server Name: Example Name",
390
      "imageRef": "da7a211f-...-f901ce81a3e6",
391
      "flavorRef": 289,
392
      "personality": [
393
        {
394
          "path": "/Users/myusername/personlities/example1.file",
395
          "contents": "some data to inject",
396
          "group": "remotely-set user group",
397
          "mode": "rw",
398
          "owner": "ausername"
399
        }, {
400
          "path": "/Users/myusername/personlities/example2.file",
401
          "contents": "some more data to inject",
402
          "group": "",
403
          "mode": "r",
404
          "owner": "anotherusername"
405
        }
406
      ],
407
      "metadata": {
408
        "values": {
409
          "EloquentDescription": "Example server with personality",
410
          "ShortDescription": "Trying VMs"
411
        }
412
      }
413
    }
414
  }
415

    
416
.. rubric:: Response
417

    
418
=========================== =====================
419
Return Code                 Description
420
=========================== =====================
421
200 (OK)                    Request succeeded
422
400 (Bad Request)           Malformed request data
423
401 (Unauthorized)          Missing or expired user token
424
403 (Forbidden)             User is not allowed to perform this operation
425
404 (Not Found)             Image or Flavor not found
426
413 (Over Limit)            Exceeded some resource limit (#VMs, personality
427
size, etc.)
428
415 (Bad Media Type)        
429
500 (Internal Server Error) The request cannot be completed because of an
430
\                           internal error
431
503 (Service Unavailable)   No available backends or service currently
432
\                           unavailable
433
=========================== =====================
434

    
435
|
436

    
437
Response body contents::
438

    
439
  server: {
440
    <server attribute>: <value>,
441
    ...
442
  }
443

    
444
Server attributes are `listed here <#server-ref>`_.
445

    
446
*Example Create Server Response: JSON*
447

    
448
.. code-block:: javascript
449

    
450
  {
451
    "server": {
452
      "id": 28130
453
      "status": "BUILD",
454
      "updated": "2013-04-10T13:52:18.140686+00:00",
455
      "hostId": "",
456
      "name": "My Server Name: Example Name",
457
      "imageRef": "da7a211f-...-f901ce81a3e6",
458
      "created": "2013-04-10T13:52:17.085402+00:00",
459
      "flavorRef": 289,
460
      "adminPass": "fKCqlZe2at",
461
      "suspended": false,
462
      "progress": 0
463
      "metadata": {
464
        "values": {
465
          "EloquentDescription": "Example server with personality",
466
          "ShortDescription": "Trying VMs"
467
        }
468
      }
469
    }
470
  }
471

    
472
*Example Create Server Response: XML*
473

    
474
.. code-block:: xml
475

    
476
  <?xml version="1.0" encoding="UTF-8"?>
477
  <server xmlns="http://docs.openstack.org/compute/api/v1.1"\
478
    xmlns:atom="http://www.w3.org/2005/Atom"
479
    id="1"
480
    status="BUILD"
481
    hostId="",
482
    name="My Server Name: Example Name"
483
    imageRef="da7a211f-...-f901ce81a3e6"
484
    created="2013-04-10T13:52:17.085402+00:00"
485
    flavorRef="289"
486
    adminPass="fKCqlZe2at"
487
    suspended="false"
488
    progress="0"
489
  />
490

    
491
Get Server Stats
492
................
493

    
494
.. note:: This operation is not part of OS/Compute v2.
495

    
496
This operation returns URLs of graphs showing CPU and Network statistics.
497

    
498
.. rubric:: Request
499

    
500
============================== ====== ======== ==========
501
URI                            Method Cyclades OS/Compute
502
============================== ====== ======== ==========
503
``/servers/<server-id>/stats`` GET    ✔        **✘**
504
============================== ====== ======== ==========
505

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

    
508
|
509

    
510
==============  ========================= ======== ==========
511
Request Header  Value                     Cyclades OS/Compute
512
==============  ========================= ======== ==========
513
X-Auth-Token    User authentication token required required
514
==============  ========================= ======== ==========
515

    
516
|
517

    
518
================= ===============
519
Request Parameter Value          
520
================= ===============
521
json              Respond in json
522
xml               Respond in xml 
523
================= ===============
524

    
525
* **json** and **xml** parameters are mutually exclusive. If none supported,
526
the response will be formated in json.
527

    
528
.. note:: Request body should be empty
529

    
530
.. rubric:: Response
531

    
532
=========================== =====================
533
Return Code                 Description
534
=========================== =====================
535
200 (OK)                    Request succeeded
536
400 (Bad Request)           Invalid server ID or Server deleted
537
401 (Unauthorized)          Missing or expired user token
538
403 (Forbidden)             Administratively suspended server
539
404 (Not Found)             Server not found
540
500 (Internal Server Error) The request cannot be completed because of an
541
\                           internal error
542
503 (Service Unavailable)   The server is not currently available
543
=========================== =====================
544

    
545
|
546

    
547
Response body contents::
548

    
549
  stats: {<parameter>: <value> }
550

    
551
============= ======================
552
Parameter     Description
553
============= ======================
554
serverRef     Server ID
555
refresh       Refresh frequency
556
cpuBar        Latest CPU load graph URL
557
cpuTimeSeries CPU load / time graph URL
558
netBar        Latest Network load graph URL
559
netTimeSeries Network load / time graph URL
560
============= ======================
561

    
562
* **refresh** is the recommended sampling rate
563

    
564
*Example Get Server Stats Response: JSON*
565

    
566
.. code-block:: javascript
567

    
568
  {
569
    "stats": {
570
      "serverRef": 1,
571
      "refresh": 60,
572
      "cpuBar": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-bar.png",
573
      "cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-ts.png",
574
      "netBar": "http://stats.okeanos.grnet.gr/b9a...048c/net-bar.png",
575
      "netTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/net-ts.png"
576
    }
577
  }
578

    
579
*Example Get Network Details Response: XML*
580

    
581
.. code-block:: xml
582

    
583
  <?xml version="1.0" encoding="UTF-8"?>
584
  <stats xmlns="http://docs.openstack.org/compute/api/v1.1"\
585
    xmlns:atom="http://www.w3.org/2005/Atom"
586
    serverRef="1"
587
    refresh="60"
588
    cpuBar="https://www.example.com/stats/snf-42/cpu-bar/",
589
    netTimeSeries="https://example.com/stats/snf-42/net-ts/",
590
    netBar="https://example.com/stats/snf-42/net-bar/",
591
    cpuTimeSeries="https://www.example.com/stats/snf-42/cpu-ts/"
592
  </stats>
593

    
594
Get Server Diagnostics
595
......................
596

    
597
.. note:: This operation is not part of OS/Compute v2.
598

    
599
This operation returns diagnostic information (logs) for a server.
600

    
601
.. rubric:: Request
602

    
603
==================================== ====== ======== ==========
604
URI                                  Method Cyclades OS/Compute
605
==================================== ====== ======== ==========
606
``/servers/<server-id>/diagnostics`` GET    ✔        **✘**
607
==================================== ====== ======== ==========
608

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

    
611
|
612

    
613
==============  ========================= ======== ==========
614
Request Header  Value                     Cyclades OS/Compute
615
==============  ========================= ======== ==========
616
X-Auth-Token    User authentication token required required
617
==============  ========================= ======== ==========
618

    
619
.. note:: Request parameters should be empty
620

    
621
.. note:: Request body should be empty
622

    
623
.. rubric:: Response
624

    
625
=========================== =====================
626
Return Code                 Description
627
=========================== =====================
628
200 (OK)                    Request succeeded
629
400 (Bad Request)           Invalid server ID or Server deleted
630
401 (Unauthorized)          Missing or expired user token
631
403 (Forbidden)             Administratively suspended server
632
404 (Not Found)             Server not found
633
500 (Internal Server Error) The request cannot be completed because of an
634
\                           internal error
635
503 (Service Unavailable)   The server is not currently available
636
=========================== =====================
637

    
638
|
639

    
640
Response body contents::
641

    
642
  [
643
    {
644
      <diagnostic attribute}: <value>,
645
      ...
646
    }, {
647
      <diagnostic attribute}: <value>,
648
      ...
649
    },
650
    ...
651
  ]
652

    
653
==================== ===========
654
Diagnostic attribute Description
655
==================== ===========
656
level                Debug level
657
created              Log entry timestamp
658
source               Log source proccess
659
source_date          Log source date
660
message              Log description
661
details              Detailed log description
662
==================== ===========
663

    
664
*Example Get Server Diagnostics Response: JSON*
665

    
666
.. code-block:: javascript
667

    
668
  [
669
    {
670
      "level": "DEBUG",
671
      "created": "2013-04-09T15:25:53.965144+00:00",
672
      "source": "image-helper-task-start",
673
      "source_date": "2013-04-09T15:25:53.954695+00:00",
674
      "message": "FixPartitionTable",
675
      "details": null
676
    }, {
677
      "level": "DEBUG",
678
      "created": "2013-04-09T15:25:46.413718+00:00",
679
      "source": "image-info",
680
      "source_date": "2013-04-09T15:25:46.404477+00:00",
681
      "message": "Starting customization VM...",
682
      "details": null
683
    }, {
684
      "level": "DEBUG",
685
      "created": "2013-04-09T15:25:46.207038+00:00",
686
      "source": "image-info",
687
      "source_date": "2013-04-09T15:25:46.197183+00:00",
688
      "message": "Image copy finished.",
689
      "details": "All operations finished as they should. No errors reported."
690
    }
691
  ]
692

    
693
Get Server Details
694
..................
695

    
696
This operation returns detailed information for a virtual server
697

    
698
.. rubric:: Request
699

    
700
======================== ====== ======== ==========
701
URI                      Method Cyclades OS/Compute
702
======================== ====== ======== ==========
703
``/servers/<server id>`` GET    ✔        ✔
704
======================== ====== ======== ==========
705

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

    
708
|
709

    
710
==============  ========================= ======== ==========
711
Request Header  Value                     Cyclades OS/Compute
712
==============  ========================= ======== ==========
713
X-Auth-Token    User authentication token required required
714
==============  ========================= ======== ==========
715

    
716
.. note:: Request parameters should be empty
717

    
718
.. note:: Request body should be empty
719

    
720
.. rubric:: Response
721

    
722
=========================== =====================
723
Return Code                 Description
724
=========================== =====================
725
200 (OK)                    Request succeeded
726
400 (Bad Request)           Malformed server id
727
401 (Unauthorized)          Missing or expired user token
728
403 (Forbidden)             Administratively suspended server
729
404 (Not Found)             Server not found
730
500 (Internal Server Error) The request cannot be completed because of an
731
\                           internal error
732
503 (Service Unavailable)   No available backends or service currently
733
\                           unavailable
734
=========================== =====================
735

    
736
|
737

    
738
Response body contents::
739

    
740
  server: {
741
    <server attribute>: <value>,
742
    ...
743
  }
744

    
745
================= ====================== ======== ==========
746
Server Attributes Description            Cyclades OS/Compute
747
================= ====================== ======== ==========
748
id                The server id          ✔        ✔
749
name              The server name        ✔        ✔
750
hostId            Server playground      empty    ✔
751
created           Creation date          ✔        ✔
752
updated           Creation date          ✔        ✔
753
flavorRef         The flavor id          ✔        **✘**
754
flavor            The flavor id          **✘**    ✔
755
imageRef          The image id           ✔        **✘**
756
image             The image id           **✘**    ✔
757
progress          Build progress         ✔        ✔
758
status            Server status          ✔        ✔
759
suspended         If server is suspended ✔        **✘**
760
attachments       Network interfaces     ✔        **✘**
761
addresses         Network interfaces     **✘**    ✔
762
metadata          Server custom metadata ✔        ✔
763
diagnostics       Diagnostic information ✔        **✘**
764
================= ====================== ======== ==========
765

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

    
769
* **progress** is changing while the server is building up and has values
770
  between 0 and 100. When it reaches 100 the server is built.
771

    
772
* **status** refers to `the status <#status-ref>`_ of the server
773

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

    
777
* **attachments** in Cyclades are lists of network interfaces (NICs).
778
  **Attachments** are different to OS/Compute's **addresses**. The former is a
779
  list of the server's `network interface connections <#nic-ref>`_ while the
780
  later is just a list of networks. Thus, a Cyclades virtual server may be
781
  connected to the same network through more than one distinct network
782
  interfaces.
783

    
784
* **diagnostics** is a list of items that contain key:value information useful
785
  for diagnosing the server behavior and may be used by the administrators of
786
  deployed Synnefo setups.
787

    
788
*Example Details for server with id 42042: JSON*
789

    
790
.. code-block:: javascript
791

    
792
  {
793
    "server": {
794
      "id": 42042,
795
      "name": "My Example Server",
796
      "status": "ACTIVE",
797
      "updated": "2013-04-18T10:09:57.824266+00:00",
798
      "hostId": "",
799
      "imageRef": "926a1bc5-2d85-49d4-aebe-0fc127ed89b9",
800
      "created": "2013-04-18T10:06:58.288273+00:00",
801
      "flavorRef": 22,
802
      "attachments": {
803
        "values": [{
804
          "network_id": "1888",
805
          "mac_address": "aa:0c:f5:ad:16:41",
806
          "firewallProfile": "DISABLED",
807
          "ipv4": "83.212.112.56",
808
          "ipv6": "2001:648:2ffc:1119:a80c:f5ff:fead:1641",
809
          "id": "nic-42042-0"
810
        }]
811
      },
812
      "suspended": false,
813
      "diagnostics": [{
814
        "level": "DEBUG",
815
        "created": "2013-04-18T10:09:52.776920+00:00",
816
        "source": "image-info",
817
        "source_date": "2013-04-18T10:09:52.709791+00:00",
818
        "message": "Image customization finished successfully.",
819
        "details": null
820
      }],
821
      "progress": 100,
822
      "metadata": {
823
        "values": {"OS": "windows", "users": "Administrator"}
824
      }
825
    }
826
  }
827

    
828
.. note:: the ``values`` layer is not featured in OS/Compute API
829

    
830
Rename Server
831
.............
832

    
833
Modify the ``name`` attribute of a virtual server. OS/Compute API also features
834
the modification of IP addresses
835

    
836
.. rubric:: Response
837

    
838
======================== ====== ======== ==========
839
URI                      Method Cyclades OS/Compute
840
======================== ====== ======== ==========
841
``/servers/<server id>`` PUT    ✔        ✔
842
======================== ====== ======== ==========
843

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

    
846
|
847

    
848
==============  ========================= ======== ==========
849
Request Header  Value                     Cyclades OS/Compute
850
==============  ========================= ======== ==========
851
X-Auth-Token    User authentication token required required
852
Content-Type    Type or request body      required required
853
Content-Length  Length of request body    required required
854
==============  ========================= ======== ==========
855

    
856
**Example Request Headers**::
857

    
858
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
859
  Content-Type:   application/json
860
  Content-Length: 54
861

    
862
.. note:: Request parameters should be empty
863

    
864
Request body contents::
865

    
866
  server: {
867
    <server attribute>: <value>,
868
    ...
869
  }
870

    
871
=========== ==================== ======== ==========
872
Attribute   Description          Cyclades OS/Compute
873
=========== ==================== ======== ==========
874
name        The server name      ✔        ✔
875
accessIPv4  IP v4 address        **✘**    ✔
876
accessIPv6  IP v6 address        **✘**    ✔
877
=========== ==================== ======== ==========
878

    
879
* Cyclades support multiple network connections per virtual server, which
880
  explains the above differences in request body attributes.
881

    
882
*Example Rename Server Request: JSON*
883

    
884
.. code-block:: javascript
885

    
886
  {"server": {"name": "A new name for my virtual server"}}
887

    
888
.. rubric:: Response
889

    
890
=========================== =====================
891
Return Code                 Description
892
=========================== =====================
893
204 (OK)                    Request succeeded
894
400 (Bad Request)           Malformed request or malformed server id
895
401 (Unauthorized)          Missing or expired user token
896
403 (Forbidden)             User is not allowed to perform this operation
897
404 (Not Found)             Server not found
898
415 (Bad Media Type)
899
409 (Build In Progress)     Server is not ready yet
900
500 (Internal Server Error) The request cannot be completed because of an
901
\                           internal error
902
503 (Service Unavailable)   No available backends or service currently
903
\                           unavailable
904
=========================== =====================
905

    
906
.. note:: In case of a 204 return code, there will be no request results
907
  according to the Cyclades API. Compute OS API suggests that response should
908
  include the new server details.
909

    
910
Delete Server
911
.............
912

    
913
Delete a virtual server. When a server is deleted, all its connections are
914
deleted as well.
915

    
916
.. rubric:: Request
917

    
918
======================== ====== ======== ==========
919
URI                      Method Cyclades OS/Compute
920
======================== ====== ======== ==========
921
``/servers/<server id>`` DELETE ✔        ✔
922
======================== ====== ======== ==========
923

    
924
* **server-id** is the identifier of the virtual server.
925

    
926
|
927

    
928
==============  ========================= ======== ==========
929
Request Header  Value                     Cyclades OS/Compute
930
==============  ========================= ======== ==========
931
X-Auth-Token    User authentication token required required
932
==============  ========================= ======== ==========
933

    
934
.. note:: Request parameters should be empty
935

    
936
.. note:: Request body should be empty
937

    
938
.. rubric:: Response
939

    
940
=========================== =====================
941
Return Code                 Description
942
=========================== =====================
943
204 (OK)                    Request succeeded
944
400 (Bad Request)           Malformed server id or machine already deleted
945
401 (Unauthorized)          Missing or expired user token
946
404 (Not Found)             Server not found
947
409 (Build In Progress)     Server is not ready yet
948
500 (Internal Server Error) The request cannot be completed because of an
949
\                           internal error
950
503 (Service Unavailable)   Action not supported or service currently
951
\                           unavailable
952
=========================== =====================
953

    
954
.. note:: In case of a 204 code, response body should be empty
955

    
956
List Server Addresses
957
.....................
958

    
959
List all network connections of a server. In Cyclades API, connections are
960
represented as Network Connection Interfaces (NICs), which describe a server -
961
network relation through their respective identifiers. This mechanism ensures
962
flexibility and multiple networks connecting the same virtual servers.
963

    
964
The Synnefo/Cyclades approach in this matter differs substantially to the
965
`one suggested by the OS/Compute API <http://docs.openstack.org/api/openstack-compute/2/content/List_Addresses-d1e3014.html>`_.
966

    
967
.. rubric:: Request
968

    
969
============================ ====== ======== ==========
970
URI                          Method Cyclades OS/Compute
971
============================ ====== ======== ==========
972
``/servers/<server id>/ips`` GET    ✔        ✔
973
============================ ====== ======== ==========
974

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

    
977
|
978

    
979
==============  ========================= ======== ==========
980
Request Header  Value                     Cyclades OS/Compute
981
==============  ========================= ======== ==========
982
X-Auth-Token    User authentication token required required
983
==============  ========================= ======== ==========
984

    
985
.. note:: Request parameters should be empty
986

    
987
.. note:: Request body should be empty
988

    
989
.. rubric:: Response
990

    
991
=========================== =====================
992
Return Code                 Description
993
=========================== =====================
994
200 (OK)                    Request succeeded
995
400 (Bad Request)           Malformed server id or machine already deleted
996
401 (Unauthorized)          Missing or expired user token
997
404 (Not Found)             Server not found
998
409 (Build In Progress)     Server is not ready yet
999
500 (Internal Server Error) The request cannot be completed because of an
1000
\                           internal error
1001
503 (Service Unavailable)   Service currently unavailable
1002
=========================== =====================
1003

    
1004
Response body contents::
1005

    
1006
  addresses: {values: [
1007
    {
1008
      <NIC attribute>: <value>,
1009
      ...
1010
    },
1011
    ...
1012
  ]}
1013

    
1014
A Network Interface Connection (or NIC) connects the current server to a
1015
network, through their respective identifiers. More information in NIC
1016
attributes are `enlisted here <#nic-ref>`_.
1017

    
1018
*Example List Addresses: JSON*
1019

    
1020
.. code-block:: javascript
1021

    
1022
  {
1023
    "addresses": {
1024
      "values": [
1025
        {
1026
          "id": "nic-25455-0"
1027
          "network_id": "1",
1028
          "mac_address": "aa:00:03:7a:84:bb",
1029
          "firewallProfile": "DISABLED",
1030
          "ipv4": "192.168.0.27",
1031
          "ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb",
1032
        }, {
1033
          "id": "nic-25455-1"
1034
          "network_id": "7",
1035
          "mac_address": "aa:00:03:7a:84:cc",
1036
          "firewallProfile": "DISABLED",
1037
          "ipv4": "192.168.0.28",
1038
          "ipv6": "2002:646:2fec:1222:a820:3fd:fe7a:84bc",
1039
        },
1040
      ]
1041
    }
1042
  }
1043

    
1044
Get Server NICs by Network
1045
..........................
1046

    
1047
Return the NIC that connects a server to a network.
1048

    
1049
The semantics of this operation are substantially different to the respective
1050
OS/Compute
1051
`List Addresses by Network semantics <http://docs.openstack.org/api/openstack-compute/2/content/List_Addresses_by_Network-d1e3118.html>`_.
1052

    
1053
.. rubric:: Request
1054

    
1055
========================================= ====== ======== ==========
1056
URI                                       Method Cyclades OS/Compute
1057
========================================= ====== ======== ==========
1058
``/servers/<server id>/ips/<network id>`` GET    ✔        ✔
1059
========================================= ====== ======== ==========
1060

    
1061
* **server id** is the identifier of the virtual server
1062

    
1063
* **network id** is the identifier of the network
1064

    
1065
|
1066

    
1067
==============  ========================= ======== ==========
1068
Request Header  Value                     Cyclades OS/Compute
1069
==============  ========================= ======== ==========
1070
X-Auth-Token    User authentication token required required
1071
==============  ========================= ======== ==========
1072

    
1073
.. note:: Request parameters should be empty
1074

    
1075
.. note:: Request body should be empty
1076

    
1077
.. rubric:: Response
1078

    
1079
=========================== =====================
1080
Return Code                 Description
1081
=========================== =====================
1082
200 (OK)                    Request succeeded
1083
400 (Bad Request)           Malformed server id or machine already deleted
1084
401 (Unauthorized)          Missing or expired user token
1085
404 (Not Found)             Server not found
1086
409 (Build In Progress)     Server is not ready yet
1087
500 (Internal Server Error) The request cannot be completed because of an
1088
\                           internal error
1089
503 (Service Unavailable)   Service currently unavailable
1090
=========================== =====================
1091

    
1092
|
1093

    
1094
Response body contents::
1095

    
1096
  network: {
1097
    <NIC attributes>: <value>,
1098
    ...
1099
  }
1100

    
1101
Network Interface Connection (NIC) attributes are listed `here <#nic-ref>`_.
1102

    
1103
**List Server NICs Example with server id 25455, network id 7: JSON**
1104

    
1105
.. code-block:: javascript
1106

    
1107
  {
1108
    "network": {
1109
      "id": "nic-25455-0"
1110
      "network_id": "7",
1111
      "mac_address": "aa:00:03:7a:84:bb",
1112
      "firewallProfile": "DISABLED",
1113
      "ipv4": "192.168.0.27",
1114
      "ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb",
1115
    }
1116
  }
1117

    
1118

    
1119
List Server Metadata
1120
....................
1121

    
1122
List the metadata of a server
1123

    
1124
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
1125
  besides the different URI.
1126

    
1127
.. rubric:: Request
1128

    
1129
================================= ====== ======== ==========
1130
URI                               Method Cyclades OS/Compute
1131
================================= ====== ======== ==========
1132
``/servers/<server-id>/meta``     GET    ✔        **✘**
1133
``/servers/<server-id>/metadata`` GET    **✘**    ✔
1134
================================= ====== ======== ==========
1135

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

    
1138
|
1139

    
1140
==============  ========================= ======== ==========
1141
Request Header  Value                     Cyclades OS/Compute
1142
==============  ========================= ======== ==========
1143
X-Auth-Token    User authentication token required required
1144
==============  ========================= ======== ==========
1145

    
1146
.. note:: Request parameters should be empty
1147

    
1148
.. note:: Request body should be empty
1149

    
1150
.. rubric:: Response
1151

    
1152
=========================== =====================
1153
Return Code                 Description
1154
=========================== =====================
1155
200 (OK)                    Request succeeded
1156
400 (Bad Request)           Invalid server ID or Malformed request
1157
401 (Unauthorized)          Missing or expired user token
1158
403 (Forbidden)             Administratively suspended server
1159
404 (Not Found)             Server not found
1160
500 (Internal Server Error) The request cannot be completed because of an
1161
\                           internal error
1162
503 (Service Unavailable)   The server is not currently available
1163
=========================== =====================
1164

    
1165
Response body contents::
1166

    
1167
  metadata: {values:
1168
    {
1169
      <metadatum key>: <value>,
1170
      ...
1171
    }
1172
  }
1173

    
1174
*Example List Server Metadata: JSON*
1175

    
1176
.. code-block:: javascript
1177

    
1178
  {
1179
    "metadata": {
1180
      "values": {
1181
        "OS": "Linux",
1182
        "users": "root"
1183
      }
1184
    }
1185
  }
1186

    
1187
.. note:: In OS/Compute API  the ``values`` level is missing from the response.
1188

    
1189
Set / Update Server Metadata
1190
............................
1191

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

    
1200
In Cyclades API, metadata keys which are not referred by the operation will
1201
remain intact, while metadata referred by the operation will be overwritten.
1202

    
1203
.. rubric:: Request
1204

    
1205
================================= ====== ======== ==========
1206
URI                               Method Cyclades OS/Compute
1207
================================= ====== ======== ==========
1208
``/servers/<server-id>/meta``     POST    ✔       **✘**
1209
``/servers/<server-id>/metadata`` PUT    **✘**    ✔
1210
``/servers/<server-id>/metadata`` POST   **✘**    ✔
1211
================================= ====== ======== ==========
1212

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

    
1215
|
1216

    
1217
==============  ========================= ======== ==========
1218
Request Header  Value                     Cyclades OS/Compute
1219
==============  ========================= ======== ==========
1220
X-Auth-Token    User authentication token required required
1221
Content-Type    Type or request body      required required
1222
Content-Length  Length of request body    required required
1223
==============  ========================= ======== ==========
1224

    
1225
**Example Request Headers**::
1226

    
1227
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
1228
  Content-Type:   application/json
1229
  Content-Length: 56
1230

    
1231
.. note:: Request parameters should be empty
1232

    
1233
Request body contents::
1234

    
1235
  metadata: {
1236
    <metadatum key>: <value>,
1237
    ...
1238
  }
1239

    
1240
*Example Request Set / Update Server Metadata: JSON*
1241

    
1242
.. code-block:: javascript
1243

    
1244
  {"metadata": {"role": "webmail", "users": "root,maild"}}
1245

    
1246
.. rubric:: Response
1247

    
1248
=========================== =====================
1249
Return Code                 Description
1250
=========================== =====================
1251
201 (OK)                    Request succeeded
1252
400 (Bad Request)           Invalid server ID or Malformed request
1253
401 (Unauthorized)          Missing or expired user token
1254
403 (Forbidden)             Administratively suspended server
1255
404 (Not Found)             Server not found
1256
413 (OverLimit)             Maximum number of metadata exceeded
1257
500 (Internal Server Error) The request cannot be completed because of an
1258
\                           internal error
1259
503 (Service Unavailable)   The server is not currently available
1260
=========================== =====================
1261

    
1262
Response body contents::
1263

    
1264
  metadata: {
1265
    <metadatum key>: <value>,
1266
    ...
1267
  }
1268

    
1269
*Example Response Set / Update Server Metadata: JSON*
1270

    
1271
.. code-block:: javascript
1272

    
1273
  {"metadata": {"OS": "Linux", "role": "webmail", "users": "root,maild"}}
1274

    
1275
Get Server Metadata Item
1276
........................
1277

    
1278
Get the value of a specific metadatum of a virtual server
1279

    
1280
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
1281
  besides the different URI.
1282

    
1283
.. rubric:: Request
1284

    
1285
======================================= ====== ======== ==========
1286
URI                                     Method Cyclades OS/Compute
1287
======================================= ====== ======== ==========
1288
``/servers/<server-id>/meta/<key>``     GET    ✔        **✘**
1289
``/servers/<server-id>/metadata/<key>`` GET    **✘**    ✔
1290
======================================= ====== ======== ==========
1291

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

    
1294
* **key** is the key of a matadatum ``key``:``value`` pair
1295

    
1296
|
1297

    
1298
==============  ========================= ======== ==========
1299
Request Header  Value                     Cyclades OS/Compute
1300
==============  ========================= ======== ==========
1301
X-Auth-Token    User authentication token required required
1302
==============  ========================= ======== ==========
1303

    
1304
.. note:: Request parameters should be empty
1305

    
1306
.. note:: Request body should be empty
1307

    
1308
.. rubric:: Response
1309

    
1310
=========================== =====================
1311
Return Code                 Description
1312
=========================== =====================
1313
200 (OK)                    Request succeeded
1314
400 (Bad Request)           Invalid server ID or Malformed request
1315
401 (Unauthorized)          Missing or expired user token
1316
403 (Forbidden)             Administratively suspended server
1317
404 (Not Found)             Metadatum key not found
1318
500 (Internal Server Error) The request cannot be completed because of an
1319
\                           internal error
1320
503 (Service Unavailable)   The server is not currently available
1321
=========================== =====================
1322

    
1323
Response body content::
1324

    
1325
  metadata: {<metadatum key>: <value>}
1326

    
1327
*Example Get Server Metadatum for Item 'role', JSON*
1328

    
1329
.. code-block:: javascript
1330

    
1331
  {"metadata": {"role": "webmail"}}
1332

    
1333
.. note:: In OS/Compute, ``metadata`` is ``meta``
1334

    
1335
Update Server Metadatum Item
1336
.............................
1337

    
1338
Set a new or update an existing a metadum value for a virtual server.
1339

    
1340
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
1341
  besides the different URI.
1342

    
1343
.. rubric:: Request
1344

    
1345
======================================= ====== ======== ==========
1346
URI                                     Method Cyclades OS/Compute
1347
======================================= ====== ======== ==========
1348
``/servers/<server-id>/meta/<key>``     PUT    ✔        **✘**
1349
``/servers/<server-id>/metadata/<key>`` PUT    **✘**    ✔
1350
======================================= ====== ======== ==========
1351

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

    
1354
* **key** is the key of a matadatum ``key``:``value`` pair
1355

    
1356
|
1357

    
1358
==============  ========================= ======== ==========
1359
Request Header  Value                     Cyclades OS/Compute
1360
==============  ========================= ======== ==========
1361
X-Auth-Token    User authentication token required required
1362
Content-Type    Type or request body      required required
1363
Content-Length  Length of request body    required required
1364
==============  ========================= ======== ==========
1365

    
1366
**Example Request Headers**::
1367

    
1368
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
1369
  Content-Type:   application/json
1370
  Content-Length: 29
1371

    
1372
.. note:: Request parameters should be empty
1373

    
1374
Request body content::
1375

    
1376
  meta: {<metadatum key>: <value>}
1377

    
1378
*Example Request to Set or Update Server Metadatum "role": JSON*
1379

    
1380
.. code-block:: javascript
1381

    
1382
  {"meta": {"role": "gateway"}}
1383

    
1384
.. rubric:: Response
1385

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

    
1400
Response body content::
1401

    
1402
  meta: {<metadatum key>: <value>}
1403

    
1404
*Example Set or Update Server Metadatum "role":"gateway": JSON*
1405

    
1406
.. code-block:: javascript
1407

    
1408
  {"meta": {"role": "gateway"}}
1409

    
1410
Delete Server Metadatum
1411
.......................
1412

    
1413
Delete a metadatum of a virtual server
1414

    
1415
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
1416
  besides the different URI.
1417

    
1418
.. rubric:: Request
1419

    
1420
======================================= ====== ======== ==========
1421
URI                                     Method Cyclades OS/Compute
1422
======================================= ====== ======== ==========
1423
``/servers/<server-id>/meta/<key>``     DELETE ✔        **✘**
1424
``/servers/<server-id>/metadata/<key>`` DELETE **✘**    ✔
1425
======================================= ====== ======== ==========
1426

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

    
1429
* **key** is the key of a matadatum ``key``:``value`` pair
1430

    
1431
|
1432

    
1433
==============  ========================= ======== ==========
1434
Request Header  Value                     Cyclades OS/Compute
1435
==============  ========================= ======== ==========
1436
X-Auth-Token    User authentication token required required
1437
==============  ========================= ======== ==========
1438

    
1439
.. note:: Request parameters should be empty
1440

    
1441
.. note:: Request body should be empty
1442

    
1443
.. rubric:: Response
1444

    
1445
=========================== =====================
1446
Return Code                 Description
1447
=========================== =====================
1448
204 (OK)                    Request succeeded
1449
400 (Bad Request)           Invalid server ID
1450
401 (Unauthorized)          Missing or expired user token
1451
403 (Forbidden)             Administratively suspended server
1452
404 (Not Found)             Metadatum key not found
1453
500 (Internal Server Error) The request cannot be completed because of an
1454
\                           internal error
1455
503 (Service Unavailable)   The server is not currently available
1456
=========================== =====================
1457

    
1458
.. note:: In case of a 204 code, response body should be empty
1459

    
1460
Server Actions
1461
--------------
1462

    
1463
Actions are operations that are achieved through the same type of request
1464
(``POST``). There are differences in the implementations of some operations
1465
between Synnefo/Cyclades and OS/Compute. Although this document focuses on
1466
Synnefo/Cyclades, differences and similarities between the APIs are also
1467
briefed.
1468

    
1469
=============================================== ======== ==========
1470
Operations                                      Cyclades OS/Compute
1471
=============================================== ======== ==========
1472
`Start <#start-server>`_                        ✔        **✘**
1473
`Shutdown <#shutdown-server>`_                  ✔        **✘**
1474
`Reboot <#reboot-server>`_                      ✔        ✔
1475
`Get Console <#get-server-console>`_            ✔        **✘**
1476
`Set Firewall <#set-server-firewall-profile>`_  ✔        **✘**
1477
`Change Admin Password <#os-compute-specific>`_ **✘**    ✔
1478
`Rebuild <#os-compute-specific>`_               **✘**    ✔
1479
`Resize <#os-compute-specific>`_                **✘**    ✔
1480
`Confirm Resized <#os-compute-specific>`_       **✘**    ✔
1481
`Revert Resized <#os-compute-specific>`_        **✘**    ✔
1482
`Create Image <#os-compute-specific>`_          **✘**    ✔
1483
=============================================== ======== ==========
1484

    
1485
.. rubric:: Request
1486

    
1487
=============================== ====== ======== ==========
1488
URI                             Method Cyclades OS/Compute
1489
=============================== ====== ======== ==========
1490
``/servers/<server id>/action`` POST   ✔        ✔
1491
=============================== ====== ======== ==========
1492

    
1493
|
1494

    
1495
==============  ========================= ======== ==========
1496
Request Header  Value                     Cyclades OS/Compute
1497
==============  ========================= ======== ==========
1498
X-Auth-Token    User authentication token required required
1499
Content-Type    Type or request body      required required
1500
Content-Length  Length of request body    required required
1501
==============  ========================= ======== ==========
1502

    
1503
**Example Request Headers**::
1504

    
1505
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
1506
  Content-Type:   application/json
1507
  Content-Length: 32
1508

    
1509
.. note:: Request parameters should be empty
1510

    
1511
.. note:: Request body varies between operations (see bellow)
1512

    
1513
.. rubric:: Response
1514

    
1515
=========================== =====================
1516
Return Code                 Description
1517
=========================== =====================
1518
200 (OK)                    Request succeeded (for console operation)
1519
202 (OK)                    Request succeeded
1520
400 (Bad Request)           Invalid request or unknown action
1521
401 (Unauthorized)          Missing or expired user token
1522
403 (Forbidden)             User is not allowed to perform this operation
1523
500 (Internal Server Error) The request cannot be completed because of an
1524
\                           internal error
1525
503 (Service Unavailable)   The server is not currently available
1526
=========================== =====================
1527

    
1528
.. note:: Response body varies between operations (see bellow)
1529

    
1530
Start server
1531
................
1532

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

    
1535
Request body contents::
1536

    
1537
  start: {}
1538

    
1539
*Example Start Server: JSON*
1540

    
1541
.. code-block:: javascript
1542

    
1543
  {"start": {}}
1544

    
1545
.. note:: Response body should be empty
1546

    
1547
Reboot Server
1548
.............
1549

    
1550
This operation transitions a server from ``ACTIVE`` to ``REBOOT`` and then
1551
``ACTIVE`` again.
1552

    
1553
Synnefo and OS/Compute APIs offer two reboot modes: ``soft``
1554
and ``hard``. OS/Compute distinguishes between the two intermediate states
1555
(``REBOOT`` and ``HARD_REBOOT``) while rebooting, while Synnefo/Cyclades use
1556
only the ``REBOOT`` term. The expected behavior is the same, though.
1557

    
1558
Request body contents::
1559

    
1560
  reboot: {type: <reboot type>}
1561

    
1562
* **reboot type** can be either ``SOFT`` or ``HARD``.
1563

    
1564
*Example (soft) Reboot Server: JSON*
1565

    
1566
.. code-block:: javascript
1567

    
1568
  {"reboot" : { "type": "soft"}}
1569

    
1570
.. note:: Response body should be empty
1571

    
1572
Shutdown server
1573
...............
1574

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

    
1577
Request body contents::
1578

    
1579
  shutdown: {}
1580

    
1581
*Example Shutdown Server: JSON*
1582

    
1583
.. code-block:: javascript
1584

    
1585
  {"shutdown": {}}
1586

    
1587
.. note:: Response body should be empty
1588

    
1589
Get Server Console
1590
..................
1591

    
1592
.. note:: This operation is not part of OS/Compute API
1593

    
1594
The console operation arranges for an OOB console of the specified type. Only
1595
consoles of type ``vnc`` are supported for now. Cyclades server uses a running
1596
instance of vncauthproxy to setup proper VNC forwarding with a random password,
1597
then returns the necessary VNC connection info to the caller.
1598

    
1599
Request body contents::
1600

    
1601
  console: {type: vnc}
1602

    
1603
*Example Get Server Console: JSON*
1604

    
1605
.. code-block:: javascript
1606

    
1607
  {"console": {"type": "vnc" }
1608

    
1609
Response body contents::
1610

    
1611
  console: {
1612
    <vnc attribute>: <value>,
1613
    ...
1614
  }
1615

    
1616
============== ======================
1617
VNC Attributes Description
1618
============== ======================
1619
host           The vncprocy host
1620
port           vncprocy port
1621
password       Temporary password
1622
type           Connection type (only VNC)
1623
============== ======================
1624

    
1625
*Example Action Console Response: JSON*
1626

    
1627
.. code-block:: javascript
1628

    
1629
  {
1630
    "console": {
1631
      "type": "vnc",
1632
      "host": "vm42.example.org",
1633
      "port": 1234,
1634
      "password": "513NR14PN0T"
1635
    }
1636
  }
1637

    
1638
Set Server Firewall Profile
1639
...........................
1640

    
1641
The firewallProfile function sets a firewall profile for the public interface
1642
of a server.
1643

    
1644
Request body contents::
1645

    
1646
  firewallProfile: { profile: <firewall profile>}
1647

    
1648
* **firewall profile** can be ``ENABLED``, ``DISABLED`` or ``PROTECTED``
1649

    
1650
*Example Action firewallProfile: JSON**
1651

    
1652
.. code-block:: javascript
1653

    
1654
  {"firewallProfile": {"profile": "ENABLED"}}
1655

    
1656
.. note:: Response body should be empty
1657

    
1658
OS/Compute Specific
1659
...................
1660

    
1661
The following operations are meaningless or not supported in the context of
1662
Synnefo/Cyclades, but are parts of the OS/Compute API:
1663

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

    
1671

    
1672
Flavors
1673
-------
1674

    
1675
A flavor is a hardware configuration for a server.
1676

    
1677
==================================== ======================== ====== ======== ==========
1678
Description                          URI                      Method Cyclades OS/Compute
1679
==================================== ======================== ====== ======== ==========
1680
`List <#list-flavors>`_              ``/flavors``             GET    ✔        ✔
1681
\                                    ``/flavors/detail``      GET    ✔        **✘**
1682
`Get details <#get-flavor-details>`_ ``/flavors/<flavor-id>`` GET    ✔        ✔
1683
==================================== ======================== ====== ======== ==========
1684

    
1685
List Flavors
1686
............
1687

    
1688
List the flavors that are accessible by the user
1689

    
1690
.. rubric:: Request
1691

    
1692
=================== ====== ======== ==========
1693
URI                 Method Cyclades OS/Compute
1694
=================== ====== ======== ==========
1695
``/flavors``        GET    ✔        ✔
1696
``/flavors/detail`` GET    ✔        **✘**
1697
=================== ====== ======== ==========
1698

    
1699
* The detailed (``/flavors/detail``) listing in Cyclades is semantically
1700
  similar to OS/Compute regular (``/flavor``) listing. The Cyclades regular
1701
  listing semantics are Cyclades specific.
1702

    
1703
|
1704

    
1705
==============  ========================= ======== ==========
1706
Request Header  Value                     Cyclades OS/Compute
1707
==============  ========================= ======== ==========
1708
X-Auth-Token    User authentication token required required
1709
==============  ========================= ======== ==========
1710

    
1711
|
1712

    
1713
================= ===============
1714
Request Parameter Value
1715
================= ===============
1716
json              Respond in json
1717
xml               Respond in xml
1718
================= ===============
1719

    
1720
.. note:: Request body should be empty
1721

    
1722
.. rubric:: Response
1723

    
1724
=========================== =====================
1725
Return Code                 Description
1726
=========================== =====================
1727
200 (OK)                    Request succeeded
1728
400 (Bad Request)           Malformed request
1729
401 (Unauthorized)          Missing or expired user token
1730
403 (Forbidden)             Forbidden to use this flavor
1731
500 (Internal Server Error) The request cannot be completed because of an
1732
\                           internal error
1733
503 (Service Unavailable)   The server is not currently available
1734
=========================== =====================
1735

    
1736
Response code contents::
1737

    
1738
  flavors: {values[
1739
    {
1740
      <flavor attribute>: <value>,
1741
      ...
1742
    },
1743
    ...
1744
  ]}
1745

    
1746
Flavor attributes are `listed here <#flavor-ref>`_. Regular listing contains
1747
only ``id`` and ``name`` attributes.
1748

    
1749
*Example List Flavors (regular): JSON*
1750

    
1751
.. code-block:: javascript
1752

    
1753
  {
1754
    "flavors": {
1755
      "values": [
1756
        {
1757
          "id": 1,
1758
          "name": "One code",
1759
        }, {
1760
          "id": 3,
1761
          "name": "Four core",
1762
        }
1763
      ]
1764
    }
1765
  }
1766

    
1767

    
1768
*Example List Flavors (regular): XML*
1769

    
1770
.. code-block:: xml
1771

    
1772
  <?xml version="1.0" encoding="UTF-8"?>
1773
  <flavors xmlns="http://docs.openstack.org/compute/api/v1"
1774
    xmlns:atom="http://www.w3.org/2005/Atom">
1775
    <flavor id="1" name="One core"/>
1776
    <flavor id="3" name="Four core"/>
1777
  </flavors>
1778

    
1779
*Example List Flavors (detail): JSON*
1780

    
1781
.. code-block:: javascript
1782

    
1783
  {
1784
    "flavors": {
1785
      "values": [
1786
        {
1787
          "id": 1,
1788
          "name": "One core",
1789
          "ram": 1024,
1790
          "SNF:disk_template": "drbd",
1791
          "disk": 20,
1792
          "cpu": 1
1793
        }, {
1794
          "id": 3,
1795
          "name": "Four core",
1796
          "ram": 1024,
1797
          "SNF:disk_template": "drbd",
1798
          "disk": 40,
1799
          "cpu": 4
1800
        }
1801
      ]
1802
    }
1803
  }
1804

    
1805
.. note:: In Compute OS API, the ``values`` layer is missing from the response
1806

    
1807
Get Flavor Details
1808
..................
1809

    
1810
Get the configuration of a specific flavor
1811

    
1812
.. rubric:: Request
1813

    
1814
======================= ====== ======== ==========
1815
URI                     Method Cyclades OS/Compute
1816
======================= ====== ======== ==========
1817
``/flavors/<flavor-id`` GET    ✔        ✔
1818
======================= ====== ======== ==========
1819

    
1820
* **flavor-id** is the identifier of the flavor
1821

    
1822
|
1823

    
1824
==============  ========================= ======== ==========
1825
Request Header  Value                     Cyclades OS/Compute
1826
==============  ========================= ======== ==========
1827
X-Auth-Token    User authentication token required required
1828
==============  ========================= ======== ==========
1829

    
1830
|
1831

    
1832
================= ===============
1833
Request Parameter Value
1834
================= ===============
1835
json              Respond in json
1836
xml               Respond in xml
1837
================= ===============
1838

    
1839
.. note:: Request body should be empty
1840

    
1841
.. rubric:: Response
1842

    
1843
=========================== =====================
1844
Return Code                 Description
1845
=========================== =====================
1846
200 (OK)                    Request succeeded
1847
400 (Bad Request)           Malformed flavor ID
1848
401 (Unauthorized)          Missing or expired user token
1849
403 (Forbidden)             Forbidden to use this flavor
1850
404 (Not Found)             Flavor id not founmd
1851
500 (Internal Server Error) The request cannot be completed because of an
1852
\                           internal error
1853
503 (Service Unavailable)   The server is not currently available
1854
=========================== =====================
1855

    
1856
Response code contents::
1857

    
1858
  flavor: {
1859
    <flavor attribute>: <value>,
1860
    ...
1861
  }
1862

    
1863
All flavor attributes are `listed here <flavor-ref>`_.
1864

    
1865
*Example Flavor Details: JSON*
1866

    
1867
.. code-block:: javascript
1868

    
1869
  {
1870
    "flavor": {
1871
      {
1872
        "id": 1,
1873
        "name": "One core",
1874
        "ram": 1024,
1875
        "SNF:disk_template": "drbd",
1876
        "disk": 20,
1877
        "cpu": 1
1878
      }
1879
    }
1880
  }
1881

    
1882
*Example Flavor Details: XML*
1883

    
1884
.. code-block:: xml
1885

    
1886
  <?xml version="1.0" encoding="UTF-8"?>
1887
  <flavor xmlns="http://docs.openstack.org/compute/api/v1"
1888
    xmlns:atom="http://www.w3.org/2005/Atom"
1889
    id="1" name="One core" ram="1024" disk="20" cpu="1" />
1890

    
1891
Images
1892
------
1893

    
1894
An image is a collection of files used to create or rebuild a server. Synnefo
1895
deployments usually provide pre-built OS images, but custom image creation is
1896
also supported.
1897

    
1898
============================================= ===================================== ====== ======== ==========
1899
Description                                   URI                                   Method Cyclades OS/Compute
1900
============================================= ===================================== ====== ======== ==========
1901
`List <#list-images>`_                        ``/images``                           GET    ✔        ✔
1902
\                                             ``/images/detail``                    GET    ✔        ✔
1903
`Get details <#get-image-details>`_           ``/images/<image-id>``                GET    ✔        ✔
1904
`Delete <#delete-image>`_                     ``/images/<image id>``                DELETE ✔        ✔
1905
`List Metadata <#list-image-metadata>`_       ``/images/<image-id>/meta``           GET    ✔        **✘**
1906
\                                             ``/images/<image-id>/metadata``       GET    **✘**    ✔
1907
`Update Metadata <#update-image-metadata>`_   ``/images/<image-id>/meta``           POST    ✔       **✘**
1908
\                                             ``/images/<image-id>/metadata``       PUT    **✘**    ✔
1909
\                                             ``/images/<image-id>/metadata``       POST   **✘**    ✔
1910
`Get Meta Item <#get-image-metadatum>`_       ``/image/<image-id>/meta/<key>``      GET    ✔        **✘**
1911
\                                             ``/images/<image-id>/metadata/<key>`` GET    **✘**    ✔
1912
`Update Metadatum <#update-image-metadatum>`_ ``/images/<image-id>/meta/<key>``     PUT    ✔        **✘**
1913
\                                             ``/images/<image-id>/metadata/<key>`` PUT    **✘**    ✔
1914
`Delete Metadatum <#delete-image-metadatum>`_ ``/images/<image-id>/meta/<key>``     DELETE ✔        **✘**
1915
\                                             ``/images/<image-id>/metadata/<key>`` DELETE **✘**    ✔
1916
============================================= ===================================== ====== ======== ==========
1917

    
1918

    
1919
List Images
1920
...........
1921

    
1922
List all images accessible by the user
1923

    
1924
.. rubric:: Request
1925

    
1926
=================== ====== ======== ==========
1927
URI                 Method Cyclades OS/Compute
1928
=================== ====== ======== ==========
1929
``/images``        GET    ✔        ✔
1930
``/images/detail`` GET    ✔        ✔
1931
=================== ====== ======== ==========
1932

    
1933
|
1934

    
1935
==============  ========================= ======== ==========
1936
Request Header  Value                     Cyclades OS/Compute
1937
==============  ========================= ======== ==========
1938
X-Auth-Token    User authentication token required required
1939
==============  ========================= ======== ==========
1940

    
1941
|
1942

    
1943
================= ======================== ======== ==========
1944
Request Parameter Value                    Cyclades OS/Compute
1945
================= ======================== ======== ==========
1946
server            Server filter            **✘**    ✔
1947
name              Image name filter        **✘**    ✔
1948
status            Server status filter     **✘**    ✔
1949
changes-since     Change timestamp filter  ✔        ✔
1950
marker            Last list last ID filter **✘**    ✔
1951
limit             Page size filter         **✘**    ✔
1952
type              Request filter type      **✘**    ✔
1953
================= ======================== ======== ==========
1954

    
1955
* **changes-since** must be an ISO8601 date string. In Cyclades it refers to
1956
  the image ``updated_at`` attribute and it should be a date in the window
1957
  [- POLL_LIMIT ... now]. POLL_LIMIT default value is 3600 seconds except if it
1958
  is set otherwise at server side.
1959

    
1960
.. note:: Request body should be empty
1961

    
1962
.. rubric:: Response
1963

    
1964
=========================== =====================
1965
Return Code                 Description
1966
=========================== =====================
1967
200 (OK)                    Request succeeded
1968
304 (No images since date)  Can be returned if ``changes-since`` is given
1969
400 (Bad Request)           Invalid or malformed ``changes-since`` parameter
1970
401 (Unauthorized)          Missing or expired user token
1971
403 (Forbidden)             User is not allowed to perform this operation
1972
500 (Internal Server Error) The request cannot be completed because of an
1973
\                           internal error
1974
503 (Service Unavailable)   The server is not currently available
1975
=========================== =====================
1976

    
1977
Response body contents::
1978

    
1979
  images: {values: [
1980
    {
1981
      <image attribute>: <value>,
1982
      ...
1983
      metadata: {values: {
1984
        <image metadatum key>: <value>,
1985
        ...
1986
      }},
1987
      ...
1988
    },
1989
    ...
1990
  ]}
1991

    
1992
The regular response returns just ``id`` and ``name``, while the detail returns a collections of the `image attributes listed here <#image-ref>`_.
1993

    
1994
*Example List Image (detail): JSON*
1995

    
1996
.. code-block:: javascript
1997

    
1998
  {
1999
    "images: {
2000
      "values": [
2001
        {
2002
          "status": "ACTIVE",
2003
          "updated": "2013-03-02T15:57:03+00:00",
2004
          "name": "edx_saas",
2005
          "created": "2013-03-02T12:21:00+00:00",
2006
          "progress": 100,
2007
          "id": "175716...526236",
2008
          "metadata": {
2009
            "values": {
2010
              "partition_table": "msdos",
2011
              "osfamily": "linux",
2012
              "users": "root saasbook",
2013
              "exclude_task_changepassword": "yes",
2014
              "os": "ubuntu",
2015
              "root_partition": "1",
2016
              "description": "Ubuntu 12.04 LTS"
2017
            }
2018
          }
2019
        }, {
2020
          "status": "ACTIVE",
2021
          "updated": "2013-03-02T15:57:03+00:00",
2022
          "name": "edx_saas",
2023
          "created": "2013-03-02T12:21:00+00:00",
2024
          "progress": 100,
2025
          "id": "1357163d...c526206",
2026
          "metadata": {
2027
            "values": {
2028
              "partition_table": "msdos",
2029
              "osfamily": "windows",
2030
              "users": "Administratior",
2031
              "exclude_task_changepassword": "yes",
2032
              "os": "WinME",
2033
              "root_partition": "1",
2034
              "description": "Rerto Windows"
2035
            }
2036
          }
2037
        }
2038
      ]
2039
    }
2040
  }
2041

    
2042
.. note:: In Compute OS API, the ``values`` layer is missing from the response
2043

    
2044
Get Image Details
2045
.................
2046

    
2047
Get the details of a specific image
2048

    
2049
.. rubric:: Request
2050

    
2051
====================== ====== ======== ==========
2052
URI                    Method Cyclades OS/Compute
2053
====================== ====== ======== ==========
2054
``/images/<image-id>`` GET    ✔        ✔
2055
====================== ====== ======== ==========
2056

    
2057
* **image-id** is the identifier of the virtual image
2058

    
2059
|
2060

    
2061
==============  ========================= ======== ==========
2062
Request Header  Value                     Cyclades OS/Compute
2063
==============  ========================= ======== ==========
2064
X-Auth-Token    User authentication token required required
2065
==============  ========================= ======== ==========
2066

    
2067
.. note:: Request parameters should be empty
2068

    
2069
.. note:: Request body should be empty
2070

    
2071
.. rubric:: Response
2072

    
2073
=========================== =====================
2074
Return Code                 Description
2075
=========================== =====================
2076
200 (OK)                    Request succeeded
2077
400 (Bad Request)           Malformed image id
2078
401 (Unauthorized)          Missing or expired user token
2079
403 (Forbidden)             Not allowed to use this image
2080
404 (Not Found)             Image not found
2081
500 (Internal Server Error) The request cannot be completed because of an
2082
\                           internal error
2083
503 (Service Unavailable)   No available backends or service currently
2084
\                           unavailable
2085
=========================== =====================
2086

    
2087
Response body contents::
2088

    
2089
  image: {
2090
    <image attribute>: <value>,
2091
    ...
2092
    metadata: {values:{
2093
      <image metadatum key>: <value>
2094
    }}
2095
  }
2096

    
2097
Image attributes are `listed here <#image-ref>`_.
2098

    
2099
*Example Details for an image with id 6404619d-...-aef57eaff4af, in JSON*
2100

    
2101
.. code-block:: javascript
2102

    
2103
    {
2104
    "image": {
2105
      "id": "6404619d-...-aef57eaff4af",
2106
      "name": "FreeBSD",
2107
      "status": "ACTIVE",
2108
      "updated": "2013-04-24T12:06:02+00:00",
2109
      "created": "2013-04-24T11:52:16+00:00",
2110
      "progress": 100,
2111
      "metadata": {
2112
        "values": {
2113
          "kernel": "9.1 RELEASE",
2114
          "osfamily": "freebsd",
2115
          "users": "root",
2116
          "gui": "No GUI",
2117
          "sortorder": "9",
2118
          "os": "freebsd",
2119
          "root_partition": "2",
2120
          "description": "FreeBSD 9"
2121
        }
2122
      }
2123
    }
2124
  }
2125

    
2126
.. note:: In OS/Compute API, the ``values`` layer is missing.
2127

    
2128

    
2129
Delete Image
2130
............
2131

    
2132
Delete an image, by changing its status from ``ACTIVE`` to ``DELETED``.
2133

    
2134
.. rubric:: Request
2135

    
2136
====================== ====== ======== ==========
2137
URI                    Method Cyclades OS/Compute
2138
====================== ====== ======== ==========
2139
``/images/<image id>`` DELETE ✔        ✔
2140
====================== ====== ======== ==========
2141

    
2142
* **image id** is the identifier of the image
2143

    
2144
|
2145

    
2146
==============  ========================= ======== ==========
2147
Request Header  Value                     Cyclades OS/Compute
2148
==============  ========================= ======== ==========
2149
X-Auth-Token    User authentication token required required
2150
==============  ========================= ======== ==========
2151

    
2152
.. note:: Request parameters should be empty
2153

    
2154
.. note:: Request body should be empty
2155

    
2156
.. rubric:: Response
2157

    
2158
=========================== =====================
2159
Return Code                 Description
2160
=========================== =====================
2161
204 (OK)                    Request succeeded
2162
400 (Bad Request)           Invalid request or image id
2163
401 (Unauthorized)          Missing or expired user token
2164
404 (Not Found)             Image not found
2165
500 (Internal Server Error) The request cannot be completed because of an
2166
\                           internal error
2167
503 (Service Unavailable)   Action not supported or service currently
2168
\                           unavailable
2169
=========================== =====================
2170

    
2171
.. note:: In case of a 204 code, request body should be empty
2172

    
2173
List Image Metadata
2174
...................
2175

    
2176
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
2177
  besides the different URI.
2178

    
2179
.. rubric:: Request
2180

    
2181
=============================== ====== ======== ==========
2182
URI                             Method Cyclades OS/Compute
2183
=============================== ====== ======== ==========
2184
``/images/<image-id>/meta``     GET    ✔        **✘**
2185
``/images/<image-id>/metadata`` GET    **✘**    ✔
2186
=============================== ====== ======== ==========
2187

    
2188
* **image-id** is the identifier of the virtual image
2189

    
2190
|
2191

    
2192
==============  ========================= ======== ==========
2193
Request Header  Value                     Cyclades OS/Compute
2194
==============  ========================= ======== ==========
2195
X-Auth-Token    User authentication token required required
2196
==============  ========================= ======== ==========
2197

    
2198
.. note:: Request parameters should be empty
2199

    
2200
.. note:: Request body should be empty
2201

    
2202
.. rubric:: Response
2203

    
2204
=========================== =====================
2205
Return Code                 Description
2206
=========================== =====================
2207
201 (OK)                    Request succeeded
2208
400 (Bad Request)           Invalid image ID or Malformed request
2209
401 (Unauthorized)          Missing or expired user token
2210
403 (Forbidden)             Administratively suspended server
2211
404 (Not Found)             Server not found
2212
409 (Build In Progress)     The image is not ready yet
2213
500 (Internal Server Error) The request cannot be completed because of an
2214
\                           internal error
2215
503 (Service Unavailable)   The server is not currently available
2216
=========================== =====================
2217

    
2218
Response body content::
2219

    
2220
  metadata: {
2221
    values: {
2222
      <metadatum key>: <value>,
2223
    ...
2224
    }
2225
  }
2226

    
2227
*Example List Image Metadata: JSON*
2228

    
2229
.. code-block:: javascript
2230

    
2231
  {
2232
    "metadata": {
2233
      "values": {
2234
        "partition_table": "msdos",
2235
        "kernel": "3.2.0",
2236
        "osfamily": "linux",
2237
        "users": "user",
2238
        "gui": "Unity 5",
2239
        "sortorder": "3",
2240
        "os": "ubuntu",
2241
        "root_partition": "1",
2242
        "description": "Ubuntu 12 LTS"
2243
      }
2244
    }
2245
  }
2246

    
2247
.. note:: In OS/Compute API  the ``values`` level is missing from the response.
2248

    
2249
Update Image Metadata
2250
.....................
2251

    
2252
In Cyclades API, setting new metadata and updating the values of existing ones
2253
is achieved using one type of request (POST), while in OS/Compute API two
2254
different types are used (PUT and POST for
2255
`setting new <http://docs.openstack.org/api/openstack-compute/2/content/Create_or_Replace_Metadata-d1e5358.html>`_
2256
and
2257
`updating existing <http://docs.openstack.org/api/openstack-compute/2/content/Update_Metadata-d1e5208.html>`_
2258
metadata, respectively).
2259

    
2260
In Cyclades API, unmentioned metadata keys will remain intact, while metadata
2261
referred by the operation will be overwritten.
2262

    
2263
.. rubric:: Request
2264

    
2265
=============================== ====== ======== ==========
2266
URI                             Method Cyclades OS/Compute
2267
=============================== ====== ======== ==========
2268
``/images/<image-id>/meta``     POST    ✔       **✘**
2269
``/images/<image-id>/metadata`` PUT    **✘**    ✔
2270
``/images/<image-id>/metadata`` POST   **✘**    ✔
2271
=============================== ====== ======== ==========
2272

    
2273
* **image-id** is the identifier of the virtual image
2274

    
2275
|
2276

    
2277
==============  ========================= ======== ==========
2278
Request Header  Value                     Cyclades OS/Compute
2279
==============  ========================= ======== ==========
2280
X-Auth-Token    User authentication token required required
2281
Content-Type    Type or request body      required required
2282
Content-Length  Length of request body    required required
2283
==============  ========================= ======== ==========
2284

    
2285
**Example Request Headers**::
2286

    
2287
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
2288
  Content-Type:   application/json
2289
  Content-Length: 52
2290

    
2291
.. note:: Request parameters should be empty
2292

    
2293
Request body content::
2294

    
2295
  metadata: {
2296
    <metadatum key>: <value>,
2297
    ...
2298
  }
2299

    
2300
*Example Update Image Metadata Request: JSON*
2301

    
2302
.. code-block:: javascript
2303

    
2304
  {"metadata": {"NewAttr": "NewVal", "os": "Xubuntu'}}
2305

    
2306
.. rubric:: Response
2307

    
2308
=========================== =====================
2309
Return Code                 Description
2310
=========================== =====================
2311
201 (OK)                    Request succeeded
2312
400 (Bad Request)           Malformed request or image id
2313
401 (Unauthorized)          Missing or expired user token
2314
403 (Forbidden)             Not allowed to modify this image
2315
404 (Not Found)             Image or metadatum key not found
2316
413 (OverLimit)             Maximum number of metadata exceeded
2317
500 (Internal Server Error) The request cannot be completed because of an
2318
\                           internal error
2319
503 (Service Unavailable)   The server is not currently available
2320
=========================== =====================
2321

    
2322
Response body content::
2323

    
2324
  metadata: {
2325
    <metadatum key>: <value>,
2326
    ...
2327
  }
2328

    
2329
*Example Update Image Response: JSON*
2330

    
2331
.. code-block:: javascript
2332

    
2333
  {
2334
    "metadata": {
2335
      "partition_table": "msdos",
2336
      "kernel": "3.2.0",
2337
      "osfamily": "linux",
2338
      "users": "user",
2339
      "gui": "Unity 5",
2340
      "sortorder": "3",
2341
      "os": "Xubuntu",
2342
      "root_partition": "1",
2343
      "description": "Ubuntu 12 LTS",
2344
      "NewAttr": "NewVal"
2345
    }
2346
  }
2347

    
2348
Get Image Metadatum
2349
...................
2350

    
2351
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
2352
  besides the different URI.
2353

    
2354
.. rubric:: Request
2355

    
2356
===================================== ====== ======== ==========
2357
URI                                   Method Cyclades OS/Compute
2358
===================================== ====== ======== ==========
2359
``/image/<image-id>/meta/<key>``      GET    ✔        **✘**
2360
``/images/<image-id>/metadata/<key>`` GET    **✘**    ✔
2361
===================================== ====== ======== ==========
2362

    
2363
* **image-id** is the identifier of the image
2364

    
2365
* **key** is the key of a matadatum ``key``:``value`` pair
2366

    
2367
|
2368

    
2369
==============  ========================= ======== ==========
2370
Request Header  Value                     Cyclades OS/Compute
2371
==============  ========================= ======== ==========
2372
X-Auth-Token    User authentication token required required
2373
==============  ========================= ======== ==========
2374

    
2375
.. note:: Request parameters should be empty
2376

    
2377
.. note:: Request body should be empty
2378

    
2379
.. rubric:: Response
2380

    
2381
=========================== =====================
2382
Return Code                 Description
2383
=========================== =====================
2384
200 (OK)                    Request succeeded
2385
400 (Bad Request)           Malformed request or image id
2386
401 (Unauthorized)          Missing or expired user token
2387
403 (Forbidden)             Not allowed to access this information
2388
404 (Not Found)             Metadatum key not found
2389
500 (Internal Server Error) The request cannot be completed because of an
2390
\                           internal error
2391
503 (Service Unavailable)   The server is not currently available
2392
=========================== =====================
2393

    
2394
Response body content::
2395

    
2396
  metadata: {<metadatum key>: <value>}
2397

    
2398
*Example Get Image Metadatum Item: JSON*
2399

    
2400
.. code-block:: javascript
2401

    
2402
  {"metadata": {"os": "Xubuntu"}}
2403

    
2404
.. note:: In OS/Compute, ``metadata`` is ``meta``
2405

    
2406
Update Image Metadatum
2407
......................
2408

    
2409
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
2410
  besides the different URI.
2411

    
2412
.. rubric:: Request
2413

    
2414
===================================== ====== ======== ==========
2415
URI                                   Method Cyclades OS/Compute
2416
===================================== ====== ======== ==========
2417
``/images/<image-id>/meta/<key>``     PUT    ✔        **✘**
2418
``/images/<image-id>/metadata/<key>`` PUT    **✘**    ✔
2419
===================================== ====== ======== ==========
2420

    
2421
* **image-id** is the identifier of the image
2422

    
2423
* **key** is the key of a matadatum ``key``:``value`` pair
2424

    
2425
|
2426

    
2427
==============  ========================= ======== ==========
2428
Request Header  Value                     Cyclades OS/Compute
2429
==============  ========================= ======== ==========
2430
X-Auth-Token    User authentication token required required
2431
Content-Type    Type or request body      required required
2432
Content-Length  Length of request body    required required
2433
==============  ========================= ======== ==========
2434

    
2435
**Example Request Headers**::
2436

    
2437
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
2438
  Content-Type:   application/json
2439
  Content-Length: 27
2440

    
2441
|
2442

    
2443
.. note:: Request parameters should be empty
2444

    
2445
Request body content::
2446

    
2447
  meta: {<metadatum key>: <value>}
2448

    
2449
*Example Update Image Metadatum Item Request: JSON*
2450

    
2451
.. code-block:: javascript
2452

    
2453
  {"meta": {"os": "Kubuntu"}}
2454

    
2455
.. rubric:: Response
2456

    
2457
=========================== =====================
2458
Return Code                 Description
2459
=========================== =====================
2460
201 (OK)                    Request succeeded
2461
400 (Bad Request)           Malformed request or image id
2462
401 (Unauthorized)          Missing or expired user token
2463
403 (Forbidden)             Not allowed to modify this image
2464
404 (Not Found)             Metadatum key not found
2465
413 (OverLimit)             Maximum number of metadata exceeded
2466
500 (Internal Server Error) The request cannot be completed because of an
2467
\                           internal error
2468
503 (Service Unavailable)   The server is not currently available
2469
=========================== =====================
2470

    
2471
Request body content::
2472

    
2473
  meta: {<metadatum key>: <value>}
2474

    
2475
*Example Update Image Metadatum Item Response: JSON*
2476

    
2477
.. code-block:: javascript
2478

    
2479
  {"meta": {"os": "Kubuntu"}}
2480

    
2481
Delete Image Metadatum
2482
......................
2483

    
2484
Delete an image metadatum by its key.
2485

    
2486
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
2487
  besides the different URI.
2488

    
2489
.. rubric:: Request
2490

    
2491
===================================== ====== ======== ==========
2492
URI                                   Method Cyclades OS/Compute
2493
===================================== ====== ======== ==========
2494
``/images/<image-id>/meta/<key>``     DELETE ✔        **✘**
2495
``/images/<image-id>/metadata/<key>`` DELETE **✘**    ✔
2496
===================================== ====== ======== ==========
2497

    
2498
* **image-id** is the identifier of the image
2499
* **key** is the key of a matadatum ``key``:``value`` pair
2500

    
2501
|
2502

    
2503
==============  ========================= ======== ==========
2504
Request Header  Value                     Cyclades OS/Compute
2505
==============  ========================= ======== ==========
2506
X-Auth-Token    User authentication token required required
2507
==============  ========================= ======== ==========
2508

    
2509
.. note:: Request parameters should be empty
2510

    
2511
.. note:: Request body should be empty
2512

    
2513
.. rubric:: Response
2514

    
2515
=========================== =====================
2516
Return Code                 Description
2517
=========================== =====================
2518
204 (OK)                    Request succeeded
2519
400 (Bad Request)           Malformed image ID
2520
401 (Unauthorized)          Missing or expired user token
2521
403 (Forbidden)             Not allowed to modify this image
2522
404 (Not Found)             Metadatum key not found
2523
500 (Internal Server Error) The request cannot be completed because of an
2524
\                           internal error
2525
503 (Service Unavailable)   The server is not currently available
2526
=========================== =====================
2527

    
2528
.. note:: In case of a 204 code, the response body should be empty.
2529

    
2530
Networks
2531
--------
2532

    
2533
============= ======== ==========
2534
BASE URI      Cyclades OS/Compute
2535
============= ======== ==========
2536
``/networks`` ✔        **✘**
2537
============= ======== ==========
2538

    
2539
The Network part of Cyclades API is not supported by the OS/Compute API,
2540
although it shares some similarities with the
2541
`OS Quantum API <http://docs.openstack.org/api/openstack-network/1.0/content/API_Operations.html>`_.
2542
There are key design differences between the two systems but they exceed the
2543
scope of this document, although they affect the respective APIs.
2544

    
2545
A Server can connect to one or more networks identified by a numeric id.
2546
Networks are accessible only by the users who created them. When a network is
2547
deleted, all connections to it are deleted.
2548

    
2549
There is a special **public** network with the id *public* that can be accessed
2550
at */networks/public*. All servers are connected to **public** by default and
2551
this network can not be deleted or modified in any way.
2552

    
2553
=============================================== ================================= ======
2554
Description                                     URI                               Method
2555
=============================================== ================================= ======
2556
`List <#list-networks>`_                        ``/networks``                     GET
2557
\                                               ``/networks/detail``              GET
2558
`Create <#create-network>`_                     ``/networks``                     POST
2559
`Get details <#get-network-details>`_           ``/networks/<network-id>``        GET
2560
`Rename <#rename-network>`_                     ``/networks/<network-id>``        PUT
2561
`Delete <#delete-network>`_                     ``/networks/<network-id>``        DELETE
2562
`Connect <#connect-network-to-server>`_         ``/networks/<network-id>/action`` POST
2563
`Disconnect <#disconnect-network-from-server>`_ ``/networks/<network-id>/action`` POST
2564
=============================================== ================================= ======
2565

    
2566

    
2567
List Networks
2568
.............
2569

    
2570
This operation lists the networks associated with a users account
2571

    
2572
.. rubric:: Request
2573

    
2574
==================== ======
2575
URI                  Method
2576
==================== ======
2577
``/networks``        GET
2578
``/networks/detail`` GET
2579
==================== ======
2580

    
2581
|
2582

    
2583
==============  =========================
2584
Request Header  Value
2585
==============  =========================
2586
X-Auth-Token    User authentication token
2587
==============  =========================
2588

    
2589
.. note:: Request parameters should be empty
2590

    
2591
.. note:: Request body should be empty
2592

    
2593
.. rubric:: Response
2594

    
2595
=========================== =====================
2596
Return Code                 Description
2597
=========================== =====================
2598
204 (OK)                    Request succeeded
2599
304 (Not Modified)
2600
400 (Bad Request)           Malformed network id
2601
401 (Unauthorized)          Missing or expired user token
2602
404 (Not Found)             Network not found
2603
409 (Build In Progress)     Server is not ready yet
2604
500 (Internal Server Error) The request cannot be completed because of an
2605
\                           internal error
2606
503 (Service Unavailable)   Action not supported or service currently
2607
\                           unavailable
2608
=========================== =====================
2609

    
2610
Response body content::
2611

    
2612
  networks: {
2613
    values: [
2614
      {
2615
        <network attribute>: <value>,
2616
        ...
2617
      },
2618
      ...
2619
    ]
2620
  }
2621

    
2622
The ``detail`` operation lists the `full network attributes <#network-ref>`_,
2623
while the regular operation returns only the ``id`` and ``name`` attributes.
2624

    
2625
*Example Networks List Response: JSON (regular)*
2626

    
2627
.. code-block:: javascript
2628

    
2629
  {
2630
    "networks": {
2631
      "values": [
2632
        {"id": "1", "name": "public"},
2633
        {"id": "2", "name": "my private network"}
2634
      ]
2635
    }
2636
  }
2637

    
2638
*Example Networks List Response: JSON (detail)*
2639

    
2640
.. code-block:: javascript
2641

    
2642
  {
2643
    "networks": {
2644
      "values": [
2645
        {
2646
          "id": "1",
2647
          "name": "public",
2648
          "created": "2011-04-20T15:31:08.199640+00:00",
2649
          "updated": "2011-05-06T12:47:05.582679+00:00",
2650
          "attachments": {"values": ["nic-42-0", "nic-73-0"]}
2651
        }, {
2652
          "id": 2,
2653
          "name": "my private network",
2654
          "created": "2011-04-20T14:32:08.199640+00:00",
2655
          "updated": "2011-05-06T11:40:05.582679+00:00",
2656
          "attachments": {"values": ["nic-42-2", "nic-7-3"]}
2657
        }
2658
      ]
2659
    }
2660
  }
2661

    
2662

    
2663
Create Network
2664
..............
2665

    
2666
This operation asynchronously provisions a new network.
2667

    
2668
.. rubric:: Request
2669

    
2670
==================== ======
2671
URI                  Method
2672
==================== ======
2673
``/networks``        POST
2674
==================== ======
2675

    
2676
|
2677

    
2678
==============  =========================
2679
Request Header  Value
2680
==============  =========================
2681
X-Auth-Token    User authentication token
2682
Content-Type    Type or request body     
2683
Content-Length  Length of request body   
2684
==============  =========================
2685

    
2686
**Example Request Headers**::
2687

    
2688
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
2689
  Content-Type:   application/json
2690
  Content-Length: 60
2691

    
2692
.. note:: Request parameters should be empty
2693

    
2694
Request body content::
2695

    
2696
  network: {
2697
    <request attribute>: <value>,
2698
    ...
2699
  }
2700

    
2701
================== ======================= ======== =======
2702
Request Attributes Description             Required Default
2703
================== ======================= ======== =======
2704
name               Network name            ✔
2705
type               Network type            ✔
2706
dhcp               If use DHCP             **✘**    True
2707
cidr               IPv4 CIDR               **✘**    192.168.1.0/2
2708
cidr6              IPv6 CDIR               **✘**    null
2709
gateway            IPv4 gateway address    **✘**    null
2710
gateway6           IPv6 gateway address    **✘**    null
2711
public             If a public network     **✘**    False
2712
================== ======================= ======== =======
2713

    
2714
* **name** is a string
2715

    
2716
* **type** can be CUSTOM, IP_LESS_ROUTED, MAC_FILTERED, PHYSICAL_VLAN
2717

    
2718
* **dhcp** and **public** are flags
2719

    
2720
* **cidr**, and **gateway** are IPv4 addresses
2721

    
2722
* **cidr6**, and **gateway6** are IPv6 addresses
2723

    
2724
* **public** should better not be used. If True, a 403 error is returned.
2725

    
2726
*Example Create Network Request Body: JSON*
2727

    
2728
.. code-block:: javascript
2729

    
2730
  {"network": {"name": "private_net", "type": "MAC_FILTERED"}}
2731

    
2732
.. rubric:: Response
2733

    
2734
=========================== =====================
2735
Return Code                 Description
2736
=========================== =====================
2737
202 (OK)                    Request succeeded
2738
400 (Bad Request)           Malformed network id or request
2739
401 (Unauthorized)          Missing or expired user token
2740
403 (Forbidden)             Public network is forbidden
2741
404 (Not Found)             Network not found
2742
413 (Over Limit)            Reached networks limit
2743
415 (Bad Media Type)        Bad network type
2744
500 (Internal Server Error) The request cannot be completed because of an
2745
\                           internal error
2746
503 (Service Unavailable)   Failed to allocated network resources
2747
=========================== =====================
2748

    
2749
Response body content::
2750

    
2751
  network: {
2752
    <network attribute>: <value>,
2753
    ...
2754
  }
2755

    
2756
A list of the valid network attributes can be found `here <#network-ref>`_.
2757

    
2758
*Example Create Network Response: JSON*
2759

    
2760
.. code-block:: javascript
2761

    
2762
  {
2763
    "network": {
2764
      "status": "PENDING",
2765
      "updated": "2013-04-25T13:31:17.165237+00:00",
2766
      "name": "my private network",
2767
      "created": "2013-04-25T13:31:17.165088+00:00",
2768
      "cidr6": null,
2769
      "id": "6567",
2770
      "gateway6": null,
2771
      "public": false,
2772
      "dhcp": false,
2773
      "cidr": "192.168.1.0/24",
2774
      "type": "MAC_FILTERED",
2775
      "gateway": null,
2776
      "attachments": {"values": []}
2777
    }
2778
  }
2779

    
2780
Get Network Details
2781
...................
2782

    
2783
.. rubric:: Request
2784

    
2785
========================== ======
2786
URI                        Method
2787
========================== ======
2788
``/networks/<network-id>`` GET
2789
========================== ======
2790

    
2791
* **network-id** is the identifier of the network
2792

    
2793
|
2794

    
2795
==============  =========================
2796
Request Header  Value
2797
==============  =========================
2798
X-Auth-Token    User authentication token
2799
==============  =========================
2800

    
2801
.. note:: Request parameters should be empty
2802

    
2803
.. note:: Request body should be empty
2804

    
2805
.. rubric:: Response
2806

    
2807
=========================== =====================
2808
Return Code                 Description
2809
=========================== =====================
2810
200 (OK)                    Request succeeded
2811
400 (Bad Request)           Malformed request or network id
2812
401 (Unauthorized)          Missing or expired user token
2813
404 (Not Found)             Network not found
2814
500 (Internal Server Error) The request cannot be completed because of an
2815
\                           internal error
2816
503 (Service Unavailable)   The service is not currently available
2817
=========================== =====================
2818

    
2819
Response code content::
2820

    
2821
  network: {
2822
    <network attribute>: <value>,
2823
    ...
2824
  }
2825

    
2826
A list of network attributes can be found `here <#network-ref>`_.
2827

    
2828
*Example Get Network Details Response: JSON*
2829

    
2830
.. code-block:: javascript
2831

    
2832
  {
2833
    "network": {
2834
      "status": "PENDING",
2835
      "updated": "2013-04-25T13:31:17.165237+00:00",
2836
      "name": "my private network",
2837
      "created": "2013-04-25T13:31:17.165088+00:00",
2838
      "cidr6": null,
2839
      "id": "6567",
2840
      "gateway6": null,
2841
      "public": false,
2842
      "dhcp": false,
2843
      "cidr": "192.168.1.0/24",
2844
      "type": "MAC_FILTERED",
2845
      "gateway": null,
2846
      "attachments": {"values": []}
2847
    }
2848
  }
2849

    
2850
Rename Network
2851
..............
2852

    
2853
.. rubric:: Request
2854

    
2855
========================== ======
2856
URI                        Method
2857
========================== ======
2858
``/networks/<network-id>`` PUT
2859
========================== ======
2860

    
2861
* **network-id** is the identifier of the network
2862

    
2863
|
2864

    
2865
==============  =========================
2866
Request Header  Value
2867
==============  =========================
2868
X-Auth-Token    User authentication token
2869
Content-Type    Type or request body
2870
Content-Length  Length of request body
2871
==============  =========================
2872

    
2873
**Example Request Headers**::
2874

    
2875
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
2876
  Content-Type:   application/json
2877
  Content-Length: 33
2878

    
2879
.. note:: Request parameters should be empty
2880

    
2881
Request body content::
2882

    
2883
  network: {name: <new value>}
2884

    
2885
*Example Update Network Name Request: JSON*
2886

    
2887
.. code-block:: javascript
2888

    
2889
  {"network": {"name": "new_name"}}
2890

    
2891
.. rubric:: Response
2892

    
2893
=========================== =====================
2894
Return Code                 Description
2895
=========================== =====================
2896
204 (OK)                    Request succeeded
2897
400 (Bad Request)           Malformed request or network deleted
2898
401 (Unauthorized)          Missing or expired user token
2899
403 (Forbidden)             Administratively suspended server
2900
404 (Not Found)             Network not found
2901
413 (Over Limit)            Network Limit Exceeded
2902
415 (Bad Media Type)        Bad network type
2903
500 (Internal Server Error) The request cannot be completed because of an
2904
\                           internal error
2905
503 (Service Unavailable)   The service is not currently available
2906
=========================== =====================
2907

    
2908
.. note:: In case of a 204 code, the response body should be empty
2909

    
2910
Delete Network
2911
..............
2912

    
2913
A network is deleted as long as it is not attached to any virtual servers.
2914

    
2915
.. rubric:: Request
2916

    
2917
========================== ======
2918
URI                        Method
2919
========================== ======
2920
``/networks/<network-id>`` DELETE
2921
========================== ======
2922

    
2923
* **network-id** is the identifier of the network
2924

    
2925
|
2926

    
2927
==============  =========================
2928
Request Header  Value
2929
==============  =========================
2930
X-Auth-Token    User authentication token
2931
==============  =========================
2932

    
2933
.. note:: Request parameters should be empty
2934

    
2935
.. note:: Request body should be empty
2936

    
2937
.. rubric:: Response
2938

    
2939
=========================== =====================
2940
Return Code                 Description
2941
=========================== =====================
2942
204 (OK)                    Request succeeded
2943
400 (Bad Request)           Malformed request or network already deleted
2944
401 (Unauthorized)          Missing or expired user token
2945
403 (Forbidden)             Administratively suspended server
2946
404 (Not Found)             Network not found
2947
421 (Network In Use)        The network is in use and cannot be deleted
2948
500 (Internal Server Error) The request cannot be completed because of an
2949
\                           internal error
2950
503 (Service Unavailable)   The service is not currently available
2951
=========================== =====================
2952

    
2953
.. note:: In case of a 204 code, the response body should be empty
2954

    
2955

    
2956
Connect network to Server
2957
..........................
2958

    
2959
Connect a network to a virtual server. The effect of this operation is the
2960
creation of a NIC that connects the two parts.
2961

    
2962
.. rubric:: Request
2963

    
2964
================================= ======
2965
URI                               Method
2966
================================= ======
2967
``/networks/<network-id>/action`` POST
2968
================================= ======
2969

    
2970
* **network-id** is the identifier of the network
2971

    
2972
|
2973

    
2974
==============  =========================
2975
Request Header  Value
2976
==============  =========================
2977
X-Auth-Token    User authentication token
2978
Content-Type    Type or request body
2979
Content-Length  Length of request body
2980
==============  =========================
2981

    
2982
**Example Request Headers**::
2983

    
2984
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
2985
  Content-Type:   application/json
2986
  Content-Length: 28
2987

    
2988
.. note:: Request parameters should be empty
2989

    
2990
Response body content (connect)::
2991

    
2992
  add {serverRef: <server id to connect>}
2993

    
2994
*Example Action Add (connect to): JSON*
2995

    
2996
.. code-block:: javascript
2997

    
2998
  {"add" : {"serverRef" : 42}}
2999

    
3000
.. rubric:: Response
3001

    
3002
=========================== =====================
3003
Return Code                 Description
3004
=========================== =====================
3005
202 (OK)                    Request succeeded
3006
400 (Bad Request)           Malformed request or network already deleted
3007
401 (Unauthorized)          Missing or expired user token
3008
403 (Forbidden)             Not allowed to modify this network (e.g. public)
3009
404 (Not Found)             Network not found
3010
500 (Internal Server Error) The request cannot be completed because of an
3011
\                           internal error
3012
503 (Service Unavailable)   The service is not currently available
3013
=========================== =====================
3014

    
3015
.. note:: In case of a 202 code, the request body should be empty
3016

    
3017
Disconnect network from Server
3018
..............................
3019

    
3020
Disconnect a network from a virtual server. The effect of this operation is the
3021
deletion of the NIC that connects the two parts.
3022

    
3023
.. rubric:: Request
3024

    
3025
================================= ======
3026
URI                               Method
3027
================================= ======
3028
``/networks/<network-id>/action`` POST
3029
================================= ======
3030

    
3031
* **network-id** is the identifier of the network
3032

    
3033
|
3034

    
3035
==============  =========================
3036
Request Header  Value
3037
==============  =========================
3038
X-Auth-Token    User authentication token
3039
Content-Type    Type or request body
3040
Content-Length  Length of request body
3041
==============  =========================
3042

    
3043
**Example Request Headers**::
3044

    
3045
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
3046
  Content-Type:   application/json
3047
  Content-Length: 31
3048

    
3049
.. note:: Request parameters should be empty
3050

    
3051
Response body content (disconnect)::
3052

    
3053
  remove {serverRef: <server id to disconnect>}
3054

    
3055
*Example Action Remove (disconnect from): JSON*
3056

    
3057
.. code-block:: javascript
3058

    
3059
  {"remove" : {"serverRef" : 42}}
3060

    
3061
.. rubric:: Response
3062

    
3063
=========================== =====================
3064
Return Code                 Description
3065
=========================== =====================
3066
202 (OK)                    Request succeeded
3067
400 (Bad Request)           Malformed request or network already deleted
3068
401 (Unauthorized)          Missing or expired user token
3069
403 (Forbidden)             Not allowed to modify this network (e.g. public)
3070
404 (Not Found)             Network not found
3071
500 (Internal Server Error) The request cannot be completed because of an
3072
\                           internal error
3073
503 (Service Unavailable)   The service is not currently available
3074
=========================== =====================
3075

    
3076
.. note:: In case of a 202 code, the request body should be empty
3077

    
3078
Index of Attributes
3079
-------------------
3080

    
3081
.. _server-ref:
3082

    
3083
Server Attributes
3084
.................
3085

    
3086
================ ========================== ======== ==========
3087
Server attribute Description                Cyclades OS/Compute
3088
================ ========================== ======== ==========
3089
id               Server ID                  ✔        ✔
3090
name             Server Name                ✔        ✔
3091
status           Server Status              ✔        ✔
3092
updated          Date of last modification  ✔        ✔
3093
created          Date of creation           ✔        ✔
3094
hostId           Physical host              empty    ✔
3095
imageRef         Image ID                   ✔        **✘**
3096
image            A full image descreption   **✘**    ✔
3097
flavorRef        Flavor ID                  ✔        **✘**
3098
flavor           A full flavor description  **✘**    ✔
3099
adminPass        Superuser Password         ✔        ✔
3100
suspended        If server is suspended     ✔        ✔
3101
progress         Build progress             ✔        ✔
3102
metadata         Custom server metadata     ✔        ✔
3103
user_id          Server owner               **✘**    ✔
3104
tenant_id        Server tenant              **✘**    ✔
3105
accessIPv4       Server IPV4 net address    **✘**    ✔
3106
accessIPv6       Server IPV4 net address    **✘**    ✔
3107
addresses        Nets connected on server   **✘**    ✔
3108
links            Server links               **✘**    ✔
3109
================ ========================== ======== ==========
3110

    
3111
* **status** values are described `here <#status-ref>`_
3112

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

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

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

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

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

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

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

    
3135
.. _status-ref:
3136

    
3137
Server Status
3138
.............
3139

    
3140
============= ==================== ======== ==========
3141
Status        Description          Cyclades OS/Compute
3142
============= ==================== ======== ==========
3143
BUILD         Building             ✔        ✔
3144
ACTIVE        Up and running       ✔        ✔
3145
STOPPED       Shut down            ✔        **✘**
3146
REBOOT        Rebooting            ✔        ✔
3147
DELETED       Removed              ✔        ✔
3148
UNKNOWN       Unexpected error     ✔        ✔
3149
ERROR         In error             ✔        ✔
3150
HARD_REBOOT   Hard rebooting       **✘**    ✔
3151
PASSWORD      Resetting password   **✘**    ✔
3152
REBUILD       Rebuilding server    **✘**    ✔
3153
RESCUE        In rescue mode       **✘**    ✔
3154
RESIZE        Resizing             **✘**    ✔
3155
REVERT_RESIZE Failed to resize     **✘**    ✔
3156
SHUTOFF       Shut down by user    **✘**    ✔
3157
SUSPENDED     Suspended            **✘**    ✔
3158
VERIFY_RESIZE Waiting confirmation **✘**    ✔
3159
============= ==================== ======== ==========
3160

    
3161
.. _network-ref:
3162

    
3163
Network
3164
.......
3165

    
3166
.. note:: Networks are features in Cyclades API but not in OS/Compute API
3167

    
3168
================== ===========
3169
Network Attributes Description
3170
================== ===========
3171
id                 Network identifier
3172
name               Network name
3173
created            Date of creation
3174
updates            Date of last update
3175
cidr               IPv4 CIDR Address
3176
cidr6              IPv6 CIDR Address
3177
dhcp               IPv4 DHCP Address
3178
dhcp6              IPv6 DHCP Address
3179
gateway            IPv4 Gateway Address
3180
gateway6           IPv6 Gateway Address
3181
public             If the network is public
3182
status             Network status
3183
attachments        Network Interface Connections (NICs)
3184
================== ===========
3185

    
3186
* **id** and **name** are int and string respectively
3187

    
3188
* **created** and **updated** are ISO8061 date strings
3189

    
3190
* **public** is a boolean flag
3191

    
3192
* **status** can be PENDING, ACTIVE or DELETED
3193

    
3194
* **attachments** refers to the NICs connecting servers on that network.
3195

    
3196
.. _nic-ref:
3197

    
3198
Network Interface Connection (NIC)
3199
..................................
3200

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

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

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

    
3212
A NIC specification contains the following information:
3213

    
3214
================= ====================== ======== ==========
3215
Server Attributes Description            Cyclades OS/Compute
3216
================= ====================== ======== ==========
3217
id                The NIC id             ✔        **✘**
3218
mac_address       NIC's mac address      ✔        **✘**
3219
network_id        Network of connection  ✔        **✘**
3220
firewallProfile   The firewall profile   ✔        **✘**
3221
ipv4              IP v4 address          ✔        **✘**
3222
ipv6              IP v6 address          ✔        **✘**
3223
================= ====================== ======== ==========
3224

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

    
3229
    nic-42-0, nic-42-1, ...
3230

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

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

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

    
3238
    ENABLED, DISABLED, PROTECTED
3239

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

    
3243
.. _flavor-ref:
3244

    
3245
Flavor
3246
......
3247

    
3248
A flavor is a hardware configuration for a server. It contains the following
3249
information:
3250

    
3251
================= ==================== ======== ==========
3252
Flavor Attributes Description          Cyclades OS/Compute
3253
================= ==================== ======== ==========
3254
id                The flavor id        ✔        ✔
3255
name              The flavor name      ✔        ✔
3256
ram               Server RAM size      ✔        ✔
3257
SNF:disk_template Storage mechanism    ✔        **✘**
3258
disk              Server disk size     ✔        ✔
3259
cpu               # of Virtual CPUs    ✔        **✘**
3260
vcpus             # of Virtual CPUs    **✘**    ✔
3261
links rel         Atom link rel field  **✘**    ✔
3262
links href        Atom link href field **✘**    ✔
3263
================= ==================== ======== ==========
3264

    
3265
* **id** is the flavor unique id (a possitive integer)
3266

    
3267
* **name** is the flavor name (a string)
3268

    
3269
* **ram** is the server RAM size in MB
3270

    
3271
* **SNF:disk_template** is a reference to the underlying storage mechanism
3272
  used by the Cyclades server. It is Cyclades specific.
3273

    
3274
* **disk** the servers disk size in GB
3275

    
3276
* **cpu** and **vcpus** are semantically equivalent terms in Cyclades and
3277
  OS/Compute APIs respectively and they refer to the number of virtual CPUs
3278
  assigned to a server
3279

    
3280
* **link ref** and **link href** refer to the Atom link attributes that are
3281
  `used in OS/Compute API <http://docs.openstack.org/api/openstack-compute/2/content/List_Flavors-d1e4188.html>`_.
3282

    
3283
.. _image-ref:
3284

    
3285
Image
3286
.....
3287

    
3288
An image is a collection of files you use to create or rebuild a server.
3289

    
3290
An image item may have the fields presented bellow:
3291

    
3292
================= ====================== ======== ==========
3293
Server Attributes Description            Cyclades OS/Compute
3294
================= ====================== ======== ==========
3295
id                Image ID               ✔        ✔
3296
name              Image name             ✔        ✔
3297
updated           Last update date       ✔        ✔
3298
created           Image creation date    ✔        ✔
3299
progress          Ready status progress  ✔        **✘**
3300
status            Image status           **✘**    ✔
3301
tenant_id         Image creator          **✘**    ✔
3302
user_id           Image users            **✘**    ✔
3303
metadata          Custom metadata        ✔        ✔
3304
links             Atom links             **✘**    ✔
3305
minDisk           Minimum required disk  **✘**    ✔
3306
minRam            Minimum required RAM   **✘**    ✔
3307
================= ====================== ======== ==========
3308

    
3309
* **id** is the image id and **name** is the image name. They are both strings.
3310

    
3311
* **updated** and **created** are both ISO8601 date strings
3312

    
3313
* **progress** varies between 0 and 100 and denotes the status of the image
3314

    
3315
* **metadata** is a collection of ``key``:``values`` pairs of custom metadata,
3316
  under the tag ``values`` which lies under the tag ``metadata``.
3317

    
3318
.. note:: in OS/Compute, the ``values`` layer is missing