Revision a3d2b515

b/docs/compute-api-guide.rst
4 4
*********
5 5

  
6 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.
7
<http://www.synnefo.org>`_. The Cyclades/Compute API complies with
8
`OpenStack Compute <http://docs.openstack.org/api/openstack-compute/2/content>`_
9
with custom extensions when needed.
10 10

  
11 11
This document's goals are:
12 12

  
......
14 14
* Clarify the differences between Cyclades and OpenStack/Compute
15 15

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

  
20 21
Overview
......
74 75
API Operations
75 76
==============
76 77

  
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>/metadata``         GET    ✔        ✔
94
`Update Metadata <#set-update-server-metadata>`_    ``/servers/<server-id>/metadata``         PUT    **✘**    ✔
95
\                                                   ``/servers/<server-id>/metadata``         POST   ✔        ✔
96
`Get Meta Item <#get-server-metadata-item>`_        ``/servers/<server-id>/metadata/<key>``   GET    ✔        ✔
97
`Update Meta Item <#update-server-metadatum-item>`_ ``/servers/<server-id>/metadata/<key>``   PUT    ✔        ✔
98
`Delete Meta Item <#delete-server-metadatum>`_      ``/servers/<server-id>/metadata/<key>``   DELETE ✔        ✔
99
=================================================== ========================================= ====== ======== ==========
78
.. rubric:: Servers
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>/metadata``         GET    ✔        ✔
94
`Update Metadata <#set-update-server-metadata>`_   ``/servers/<server-id>/metadata``         PUT    **✘**    ✔
95
\                                                  ``/servers/<server-id>/metadata``         POST   ✔        ✔
96
`Get Meta Item <#get-server-metadata-item>`_       ``/servers/<server-id>/metadata/<key>``   GET    ✔        ✔
97
`Update Meta Item <#update-server-metadata-item>`_ ``/servers/<server-id>/metadata/<key>``   PUT    ✔        ✔
98
`Delete Meta Item <#delete-server-metadata>`_      ``/servers/<server-id>/metadata/<key>``   DELETE ✔        ✔
99
`Actions <#server-actions>`_                       ``servers/<server id>/action``            POST   ✔        ✔
100
================================================== ========================================= ====== ======== ==========
101

  
102
.. rubric:: Flavors
103

  
104
==================================== ======================== ====== ======== ==========
105
Description                          URI                      Method Cyclades OS/Compute
106
==================================== ======================== ====== ======== ==========
107
`List <#list-flavors>`_              ``/flavors``             GET    ✔        ✔
108
\                                    ``/flavors/detail``      GET    ✔        **✘**
109
`Get details <#get-flavor-details>`_ ``/flavors/<flavor-id>`` GET    ✔        ✔
110
==================================== ======================== ====== ======== ==========
111

  
112
.. rubric:: Images
113

  
114
=========================================== ===================================== ====== ======== ==========
115
Description                                 URI                                   Method Cyclades OS/Compute
116
=========================================== ===================================== ====== ======== ==========
117
`List <#list-images>`_                      ``/images``                           GET    ✔        ✔
118
\                                           ``/images/detail``                    GET    ✔        ✔
119
`Get details <#get-image-details>`_         ``/images/<image-id>``                GET    ✔        ✔
120
`Delete <#delete-image>`_                   ``/images/<image id>``                DELETE ✔        ✔
121
`List Metadata <#list-image-metadata>`_     ``/images/<image-id>/metadata``       GET    ✔        ✔
122
`Update Metadata <#update-image-metadata>`_ ``/images/<image-id>/metadata``       POST   ✔        ✔
123
\                                           ``/images/<image-id>/metadata``       PUT    **✘**    ✔
124
`Get Meta Item <#get-image-metadata>`_      ``/image/<image-id>/metadata/<key>``  GET    ✔        ✔
125
`Update Metadata <#update-image-metadata>`_ ``/images/<image-id>/metadata/<key>`` PUT    ✔        ✔
126
`Delete Metadata <#delete-image-metadata>`_ ``/images/<image-id>/metadata/<key>`` DELETE ✔        ✔
127
=========================================== ===================================== ====== ======== ==========
100 128

  
101 129
List Servers
102
............
130
------------
103 131

  
104 132
List all virtual servers owned by the user.
105 133

  
......
117 145
  server attributes.
118 146

  
119 147
|
120

  
121 148
==============  ========================= ======== ==========
122 149
Request Header  Value                     Cyclades OS/Compute
123 150
==============  ========================= ======== ==========
......
125 152
==============  ========================= ======== ==========
126 153

  
127 154
|
128

  
129 155
================= =================================== ======== ==========
130 156
Request Parameter Value                               Cyclades OS/Compute
131 157
================= =================================== ======== ==========
......
147 173

  
148 174
* **changes-since** must be an ISO8601 date string
149 175

  
150
.. note:: Request body should be empty
151

  
152 176
.. rubric:: Response
153 177

  
154 178
=========================== =====================
......
175 199
    }, ...
176 200
  ]
177 201

  
178
================= ====================== ======== ==========
179
Server Attributes Description            Cyclades OS/Compute
180
================= ====================== ======== ==========
181
id                The server id          ✔        ✔
182
name              The server name        ✔        ✔
183
links             Reference links        ✔        ✔
184
hostId            Server playground      empty    ✔
185
created           Creation date          ✔        ✔
186
updated           Creation date          ✔        ✔
187
flavor            The flavor id          ✔        ✔
188
image             The image id           ✔        ✔
189
progress          Build progress         ✔        ✔
190
status            Server status          ✔        ✔
191
attachments       Network interfaces     ✔        **✘**
192
addresses         Network interfaces     **✘**    ✔
193
metadata          Server custom metadata ✔        ✔
194
================= ====================== ======== ==========
195

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

  
199
* **progress** is changing while the server is building up and has values
200
  between 0 and 100. When it reaches 100 the server is built.
201

  
202
* **status** refers to `the status <#status-ref>`_ of the server
203

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

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

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

  
202
The server attributes are listed `here <#server-ref>`_
220 203

  
221 204
*Example List Servers: JSON (regular)*
222 205

  
223 206
.. code-block:: javascript
224 207

  
225
    [
208
  GET https://example.org/compute/v2.0/servers
209

  
210
  {
211
    "servers": [
226 212
      {
227 213
        "links": [
228
            {
229
                "href": "https://example.org/compute/v2.0/servers/42", 
230
                "rel": "self"
231
            }, 
232
            {
233
                "href": "https://example.org/compute/v2.0/servers/42", 
234
                "rel": "bookmark"
235
            }
214
          {
215
            "href": "https://example.org/compute/v2.0/servers/42", 
216
            "rel": "self"
217
          }, {
218
            "href": "https://example.org/compute/v2.0/servers/42", 
219
            "rel": "bookmark"
220
          }
236 221
        ],
237 222
        "id": "42",
238 223
        "name": "My Server",
239 224
      }, {
240 225
        "links": [
241
            {
242
                "href": "https://example.org/compute/v2.0/servers/43", 
243
                "rel": "self"
244
            }, 
245
            {
246
                "href": "https://example.org/compute/v2.0/servers/43", 
247
                "rel": "bookmark"
248
            }
226
          {
227
            "href": "https://example.org/compute/v2.0/servers/43", 
228
            "rel": "self"
229
          }, {
230
            "href": "https://example.org/compute/v2.0/servers/43", 
231
            "rel": "bookmark"
232
          }
249 233
        ],
250
        "id": "43",
234
        "id": "84",
251 235
        "name": "My Server",
252 236
      }
253 237
    ]
238
  }
254 239

  
255 240
*Example List Servers: JSON (detail)*
256 241

  
257 242
.. code-block:: javascript
258 243

  
259
    [
244
  {
245
    "servers": [
260 246
      {
247
        "addresses": [
248
          "2718": [
249
            {
250
              "version": 6,
251
              "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab",
252
              "OS-EXT-IPS:type": "fixed"
253
            }
254
          ],
255
          "2719": [
256
            {
257
              "version": 4,
258
              "addr": "192.168.1.2",
259
              "OS-EXT-IPS:type": "floating"
260
            }
261
          ]
262
        ],
261 263
        "attachments": [
262 264
            {
263
              "id": "nic-42-0",
264
              "network_id": "101",
265
              "mac_address": "aa:00:00:49:2e:7e",
265
              "id": "18",
266
              "network_id": "2718",
267
              "mac_address": "aa:01:02:6c:34:ab",
266 268
              "firewallProfile": "DISABLED",
267
              "ipv4": "192.168.4.5",
268
              "ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5b"
269
              "ipv4": "",
270
              "ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab"
271
              "OS-EXT-IPS:type": "fixed"
272
            }, {
273
              "id": "19",
274
              "network_id": "2719",
275
              "mac_address": "aa:00:0c:6d:34:bb",
276
              "firewallProfile": "PROTECTED",
277
              "ipv4": "192.168.1.2",
278
              "ipv6": ""
279
              "OS-EXT-IPS:type": "floating"
269 280
            }
270 281
        ],
271 282
        "links": [
283
          {
284
            "href": "https://example.org/compute/v2.0/servers/42", 
285
            "rel": "self"
286
          }, {
287
            "href": "https://example.org/compute/v2.0/servers/42", 
288
            "rel": "bookmark"
289
          }
290
        ],
291
        "image": {
292
          "id": "im4g3-1d",
293
          "links": [
272 294
            {
273
                "href": "https://example.org/compute/v2.0/servers/42", 
274
                "rel": "self"
275
            }, 
276
            {
277
                "href": "https://example.org/compute/v2.0/servers/42", 
278
                "rel": "bookmark"
295
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
296
              "rel": "self"
297
            }, {
298
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
299
              "rel": "bookmark"
300
            }, {
301
              "href": "https://example.org/image/v1.0/images/im4g3-1d", 
302
              "rel": "alternate"
279 303
            }
280
        ],
304
          ]
305
        },
306
        "suspended": false,
281 307
        "created': '2011-04-19T10:18:52.085737+00:00',
282 308
        "flavor": {
283
            "id": 1",
284
            "links": [
285
                {
286
                    "href": "https://example.org/compute/v2.0/flavors/1", 
287
                    "rel": "self"
288
                }, 
289
                {
290
                    "href": "https://example.org/compute/v2.0/flavors/1", 
291
                    "rel": "bookmark"
292
                }
293
            ]
294

  
309
          "id": 1",
310
          "links": [
311
            {
312
              "href": "https://example.org/compute/v2.0/flavors/1", 
313
              "rel": "self"
314
            }, {
315
              "href": "https://example.org/compute/v2.0/flavors/1", 
316
              "rel": "bookmark"
317
            }
318
          ]
295 319
        },
296
        "hostId": "",
297 320
        "id": "42",
298
        "image": {
299
            "id": "im4g3-1d",
300
            "links": [
301
                {
302
                    "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
303
                    "rel": "self"
304
                }, 
305
                {
306
                    "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
307
                    "rel": "bookmark"
308
                }, 
309
                {
310
                    "href": "https://example.org/image/v1.0/images/im4g3-1d", 
311
                    "rel": "alternate"
312
                }
313
            ]
314
        },
315
        "metadata": {{"foo": "bar"},
316
        "name": "My Server",
321
        "security_groups": [{"name": "default"}],
322
        "user_id": "s0m5-u5e7-1d",
323
        "accessIPv4": "",
324
        "accessIPv6": "",
325
        "progress": 100,
326
        "config_drive": "",
317 327
        "status": "ACTIVE",
318
        "updated": "2011-05-29T14:07:07.037602+00:00"
328
        "updated": "2011-05-29T14:07:07.037602+00:00",
329
        "hostId": "",
330
        "SNF:fqdn": "snf-42.vm.example.org",
331
        "key_name": null,
332
        "name": "My Server",
333
        "created": "2014-02-12T08:31:37.834542+00:00",
334
        "tenant_id": "s0m5-u5e7-1d",
335
        "SNF:port_forwarding": {},
336
        "SNF:task_state": "",
337
        "diagnostics": [
338
            {
339
                "level": "DEBUG",
340
                "created": "2014-02-12T08:31:37.834542+00:00",
341
                "source": "image-info",
342
                "source_date": "2014-02-12T08:32:35.929507+00:00",
343
                "message": "Image customization finished successfully.",
344
                "details": null
345
            }
346
        ],
347
        "metadata": {
348
            "os": "debian",
349
            "users": "root"
350
        }
319 351
      }, {
352
      {
353
        "addresses": [
354
          "2718": [
355
            {
356
              "version": 6,
357
              "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd",
358
              "OS-EXT-IPS:type": "fixed"
359
            }
360
          ],
361
          "4178": [
362
            {
363
              "version": 4,
364
              "addr": "192.168.1.3",
365
              "OS-EXT-IPS:type": "floating"
366
            }
367
          ]
368
        ],
320 369
        "attachments": [
321 370
            {
322
              "id": "nic-43-0",
323
              "mac_address": "aa:00:00:91:2f:df",
324
              "network_id": "1",
325
              "ipv4": "192.168.32.2"
326
            }, {
327
              "id": "nic-43-1",
328
              "network_id": "101",
329
              "mac_address": "aa:00:00:49:2g:7f",
371
              "id": "36",
372
              "network_id": "2718",
373
              "mac_address": "aa:01:02:6c:34:cd",
330 374
              "firewallProfile": "DISABLED",
331
              "ipv4": "192.168.32.6",
332
              "ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5c'
375
              "ipv4": "",
376
              "ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd"
377
              "OS-EXT-IPS:type": "fixed"
333 378
            }, {
334
              "id": "nic-43-2",
335
              "network_id": "101",
336
              "mac_address": "aa:00:00:51:2h:7f",
337
              "firewallProfile": "DISABLED",
338
              "ipv4": "192.168.32.7",
339
              "ipv6": "2001:638:2eec:1222:a800:ff:fef5:3f5c"
379
              "id": "38",
380
              "network_id": "4178",
381
              "mac_address": "aa:00:0c:6d:34:cc",
382
              "firewallProfile": "PROTECTED",
383
              "ipv4": "192.168.1.3",
384
              "ipv6": ""
385
              "OS-EXT-IPS:type": "floating"
340 386
            }
341 387
        ],
342 388
        "links": [
389
          {
390
            "href": "https://example.org/compute/v2.0/servers/84", 
391
            "rel": "self"
392
          }, {
393
            "href": "https://example.org/compute/v2.0/servers/84", 
394
            "rel": "bookmark"
395
          }
396
        ],
397
        "image": {
398
          "id": "im4g3-1d",
399
          "links": [
343 400
            {
344
                "href": "https://example.org/compute/v2.0/servers/43", 
345
                "rel": "self"
346
            }, 
347
            {
348
                "href": "https://example.org/compute/v2.0/servers/43", 
349
                "rel": "bookmark"
401
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
402
              "rel": "self"
403
            }, {
404
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
405
              "rel": "bookmark"
406
            }, {
407
              "href": "https://example.org/image/v1.0/images/im4g3-1d", 
408
              "rel": "alternate"
350 409
            }
351
        ],
352
        "created": "2011-05-02T20:51:08.527759+00:00",
353
        "flavor": {
354
            "id": 1",
355
            "links": [
356
                {
357
                    "href": "https://example.org/compute/v2.0/flavors/1", 
358
                    "rel": "self"
359
                }, 
360
                {
361
                    "href": "https://example.org/compute/v2.0/flavors/1", 
362
                    "rel": "bookmark"
363
                }
364
            ]
365

  
410
          ]
366 411
        },
367
        "hostId": "",
368
        "id": "43",
369
        "image": {
370
            "id": "im4g3-1d",
371
            "links": [
372
                {
373
                    "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
374
                    "rel": "self"
375
                }, 
376
                {
377
                    "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
378
                    "rel": "bookmark"
379
                }, 
380
                {
381
                    "href": "https://example.org/image/v1.0/images/im4g3-1d", 
382
                    "rel": "alternate"
383
                }
384
            ]
412
        "suspended": false,
413
        "created': '2011-04-21T10:18:52.085737+00:00',
414
        "flavor": {
415
          "id": 3",
416
          "links": [
417
            {
418
              "href": "https://example.org/compute/v2.0/flavors/3", 
419
              "rel": "self"
420
            }, {
421
              "href": "https://example.org/compute/v2.0/flavors/3", 
422
              "rel": "bookmark"
423
            }
424
          ]
385 425
        },
386
        "name": "Other Server",
387
        "description": "A sample server to showcase server requests",
388
        "progress": "0",
426
        "id": "84",
427
        "security_groups": [{"name": "default"}],
428
        "user_id": "s0m5-u5e7-1d",
429
        "accessIPv4": "",
430
        "accessIPv6": "",
431
        "progress": 100,
432
        "config_drive": "",
389 433
        "status": "ACTIVE",
390
        "updated": "2011-05-29T14:59:11.267087+00:00"
434
        "updated": "2011-05-30T14:07:07.037602+00:00",
435
        "hostId": "",
436
        "SNF:fqdn": "snf-84.vm.example.org",
437
        "key_name": null,
438
        "name": "My Other Server",
439
        "created": "2014-02-21T08:31:37.834542+00:00",
440
        "tenant_id": "s0m5-u5e7-1d",
441
        "SNF:port_forwarding": {},
442
        "SNF:task_state": "",
443
        "diagnostics": [
444
          {
445
            "level": "DEBUG",
446
            "created": "2014-02-21T08:31:37.834542+00:00",
447
            "source": "image-info",
448
            "source_date": "2014-02-21T08:32:35.929507+00:00",
449
            "message": "Image customization finished successfully.",
450
            "details": null
451
          }
452
        ],
453
        "metadata": {
454
          "os": "debian",
455
          "users": "root"
456
        }
391 457
      }
392 458
    ]
459
  }
393 460

  
394 461

  
395 462
Create Server
396
.............
463
-------------
397 464

  
398 465
Create a new virtual server
399 466

  
......
621 688
  />
622 689

  
623 690
Get Server Stats
624
................
691
----------------
625 692

  
626 693
.. note:: This operation is not part of OS/Compute v2.
627 694

  
......
717 784
    xmlns:atom="http://www.w3.org/2005/Atom"
718 785
    serverRef="1"
719 786
    refresh="60"
720
    cpuBar="https://www.example.com/stats/snf-42/cpu-bar/",
721
    netTimeSeries="https://example.com/stats/snf-42/net-ts/",
722
    netBar="https://example.com/stats/snf-42/net-bar/",
723
    cpuTimeSeries="https://www.example.com/stats/snf-42/cpu-ts/"
787
    cpuBar="https://www.example.org/stats/snf-42/cpu-bar/",
788
    netTimeSeries="https://example.org/stats/snf-42/net-ts/",
789
    netBar="https://example.org/stats/snf-42/net-bar/",
790
    cpuTimeSeries="https://www.example.org/stats/snf-42/cpu-ts/"
724 791
  </stats>
725 792

  
726 793
Get Server Diagnostics
727
......................
794
----------------------
728 795

  
729 796
.. note:: This operation is not part of OS/Compute v2.
730 797

  
......
823 890
  ]
824 891

  
825 892
Get Server Details
826
..................
893
------------------
827 894

  
828 895
This operation returns detailed information for a virtual server
829 896

  
......
906 973

  
907 974
* **attachments** in Cyclades are lists of network interfaces (NICs).
908 975
  **Attachments** are different to OS/Compute's **addresses**. The former is a
909
  list of the server's `network interface connections <#nic-ref>`_ while the
976
  list of the server's `network interface connections <#attachments-ref>`_ while the
910 977
  later is just a list of networks. Thus, a Cyclades virtual server may be
911 978
  connected to the same network through more than one distinct network
912 979
  interfaces.
......
996 1063
  }
997 1064

  
998 1065
Rename Server
999
.............
1066
-------------
1000 1067

  
1001 1068
Modify the ``name`` attribute of a virtual server. OS/Compute API also features
1002 1069
the modification of IP addresses
......
1076 1143
  include the new server details.
1077 1144

  
1078 1145
Delete Server
1079
.............
1146
-------------
1080 1147

  
1081 1148
Delete a virtual server. When a server is deleted, all its connections are
1082 1149
deleted as well.
......
1122 1189
.. note:: In case of a 204 code, response body should be empty
1123 1190

  
1124 1191
List Server Addresses
1125
.....................
1192
---------------------
1126 1193

  
1127 1194
List all network connections of a server. In Cyclades API, connections are
1128 1195
represented as Network Connection Interfaces (NICs), which describe a server -
......
1181 1248

  
1182 1249
A Network Interface Connection (or NIC) connects the current server to a
1183 1250
network, through their respective identifiers. More information in NIC
1184
attributes are `enlisted here <#nic-ref>`_.
1251
attributes are `enlisted here <#attachments-ref>`_.
1185 1252

  
1186 1253
*Example List Addresses: JSON*
1187 1254

  
......
1208 1275
  }
1209 1276

  
1210 1277
Get Server NICs by Network
1211
..........................
1278
--------------------------
1212 1279

  
1213 1280
Return the NIC that connects a server to a network.
1214 1281

  
......
1264 1331
    ...
1265 1332
  }
1266 1333

  
1267
Network Interface Connection (NIC) attributes are listed `here <#nic-ref>`_.
1334
Network Interface Connection (NIC) attributes are listed `here <#attachments-ref>`_.
1268 1335

  
1269 1336
**List Server NICs Example with server id 25455, network id 7: JSON**
1270 1337

  
......
1283 1350

  
1284 1351

  
1285 1352
List Server Metadata
1286
....................
1353
--------------------
1287 1354

  
1288 1355
List the metadata of a server
1289 1356

  
......
1346 1413
  }
1347 1414

  
1348 1415
Set / Update Server Metadata
1349
............................
1416
----------------------------
1350 1417

  
1351 1418
In Cyclades API, setting new metadata and updating the values of existing ones
1352 1419
is achieved with the same type of request (``POST``), while in OS/Compute API
......
1431 1498
  {"metadata": {"OS": "Linux", "role": "webmail", "users": "root,maild"}}
1432 1499

  
1433 1500
Get Server Metadata Item
1434
........................
1501
------------------------
1435 1502

  
1436 1503
Get the value of a specific piece of metadata of a virtual server
1437 1504

  
......
1445 1512

  
1446 1513
* **server-id** is the identifier of the virtual server
1447 1514

  
1448
* **key** is the key of a matadatum ``key``:``value`` pair
1515
* **key** is the key of a mata ``key``:``value`` pair
1449 1516

  
1450 1517
|
1451 1518

  
......
1468 1535
400 (Bad Request)           Invalid server ID or Malformed request
1469 1536
401 (Unauthorized)          Missing or expired user token
1470 1537
403 (Forbidden)             Administratively suspended server
1471
404 (Not Found)             Metadatum key not found
1538
404 (Not Found)             Meta key not found
1472 1539
500 (Internal Server Error) The request cannot be completed because of an
1473 1540
\                           internal error
1474 1541
503 (Service Unavailable)   The server is not currently available
......
1478 1545

  
1479 1546
  metadata: {<key>: <value>}
1480 1547

  
1481
*Example Get Server Metadatum for Item 'role', JSON*
1548
*Example Get Server Metadata for Item 'role', JSON*
1482 1549

  
1483 1550
.. code-block:: javascript
1484 1551

  
1485 1552
  {"metadata": {"role": "webmail"}}
1486 1553

  
1487
Update Server Metadatum Item
1488
.............................
1554
Update Server Metadata Item
1555
---------------------------
1489 1556

  
1490 1557
Set a new or update an existing a metadum value for a virtual server.
1491 1558

  
......
1523 1590

  
1524 1591
  metadata: {<key>: <value>}
1525 1592

  
1526
*Example Request to Set or Update Server Metadatum "role": JSON*
1593
*Example Request to Set or Update Server Metadata "role": JSON*
1527 1594

  
1528 1595
.. code-block:: javascript
1529 1596

  
......
1538 1605
400 (Bad Request)           Invalid server ID or Malformed request
1539 1606
401 (Unauthorized)          Missing or expired user token
1540 1607
403 (Forbidden)             Administratively suspended server
1541
404 (Not Found)             Metadatum key not found
1608
404 (Not Found)             Meta key not found
1542 1609
413 (OverLimit)             Maximum number of metadata exceeded
1543 1610
500 (Internal Server Error) The request cannot be completed because of an
1544 1611
\                           internal error
......
1549 1616

  
1550 1617
  metadata: {<key>: <value>}
1551 1618

  
1552
*Example Set or Update Server Metadatum "role":"gateway": JSON*
1619
*Example Set or Update Server Metadata "role":"gateway": JSON*
1553 1620

  
1554 1621
.. code-block:: javascript
1555 1622

  
1556 1623
  {"metadata": {"role": "gateway"}}
1557 1624

  
1558
Delete Server Metadatum
1559
.......................
1625
Delete Server Metadata
1626
----------------------
1560 1627

  
1561
Delete a metadatum of a virtual server
1628
Delete a metadata of a virtual server
1562 1629

  
1563 1630
.. rubric:: Request
1564 1631

  
......
1570 1637

  
1571 1638
* **server-id** is the identifier of the virtual server
1572 1639

  
1573
* **key** is the key of a matadatum ``key``:``value`` pair
1640
* **key** is the key of a mata ``key``:``value`` pair
1574 1641

  
1575 1642
|
1576 1643

  
......
1593 1660
400 (Bad Request)           Invalid server ID
1594 1661
401 (Unauthorized)          Missing or expired user token
1595 1662
403 (Forbidden)             Administratively suspended server
1596
404 (Not Found)             Metadatum key not found
1663
404 (Not Found)             Metadata key not found
1597 1664
500 (Internal Server Error) The request cannot be completed because of an
1598 1665
\                           internal error
1599 1666
503 (Service Unavailable)   The server is not currently available
......
1812 1879
* `Revert Resized Server <http://docs.openstack.org/api/openstack-compute/2/content/Revert_Resized_Server-d1e4024.html>`_
1813 1880
* `Create Image <http://docs.openstack.org/api/openstack-compute/2/content/Create_Image-d1e4655.html>`_
1814 1881

  
1815

  
1816
Flavors
1817
-------
1818

  
1819
A flavor is a hardware configuration for a server.
1820

  
1821
==================================== ======================== ====== ======== ==========
1822
Description                          URI                      Method Cyclades OS/Compute
1823
==================================== ======================== ====== ======== ==========
1824
`List <#list-flavors>`_              ``/flavors``             GET    ✔        ✔
1825
\                                    ``/flavors/detail``      GET    ✔        **✘**
1826
`Get details <#get-flavor-details>`_ ``/flavors/<flavor-id>`` GET    ✔        ✔
1827
==================================== ======================== ====== ======== ==========
1828

  
1829 1882
List Flavors
1830
............
1883
------------
1831 1884

  
1832 1885
List the flavors that are accessible by the user
1833 1886

  
......
1841 1894
=================== ====== ======== ==========
1842 1895

  
1843 1896
|
1844

  
1845 1897
==============  ========================= ======== ==========
1846 1898
Request Header  Value                     Cyclades OS/Compute
1847 1899
==============  ========================= ======== ==========
......
1849 1901
==============  ========================= ======== ==========
1850 1902

  
1851 1903
|
1852

  
1853 1904
================= ===============
1854 1905
Request Parameter Value
1855 1906
================= ===============
......
1979 2030
  }
1980 2031

  
1981 2032
Get Flavor Details
1982
..................
2033
------------------
1983 2034

  
1984 2035
Get the configuration of a specific flavor
1985 2036

  
......
2034 2085
    ...
2035 2086
  }
2036 2087

  
2037
All flavor attributes are `listed here <flavor-ref>`_.
2088
All flavor attributes are `listed here <#flavor-ref>`_.
2038 2089

  
2039 2090
*Example Flavor Details: JSON*
2040 2091

  
......
2072 2123
    xmlns:atom="http://www.w3.org/2005/Atom"
2073 2124
    id="1" name="One core" ram="1024" disk="20" cpu="1" />
2074 2125

  
2075
Images
2076
------
2077

  
2078
An image is a collection of files used to create or rebuild a server. Synnefo
2079
deployments usually provide pre-built OS images, but custom image creation is
2080
also supported.
2081

  
2082
============================================= ===================================== ====== ======== ==========
2083
Description                                   URI                                   Method Cyclades OS/Compute
2084
============================================= ===================================== ====== ======== ==========
2085
`List <#list-images>`_                        ``/images``                           GET    ✔        ✔
2086
\                                             ``/images/detail``                    GET    ✔        ✔
2087
`Get details <#get-image-details>`_           ``/images/<image-id>``                GET    ✔        ✔
2088
`Delete <#delete-image>`_                     ``/images/<image id>``                DELETE ✔        ✔
2089
`List Metadata <#list-image-metadata>`_       ``/images/<image-id>/metadata``       GET    ✔        ✔
2090
`Update Metadata <#update-image-metadata>`_   ``/images/<image-id>/metadata``       POST   ✔        ✔
2091
\                                             ``/images/<image-id>/metadata``       PUT    **✘**    ✔
2092
`Get Meta Item <#get-image-metadatum>`_       ``/image/<image-id>/metadata/<key>``  GET    ✔        ✔
2093
`Update Metadatum <#update-image-metadatum>`_ ``/images/<image-id>/metadata/<key>`` PUT    ✔        ✔
2094
`Delete Metadatum <#delete-image-metadatum>`_ ``/images/<image-id>/metadata/<key>`` DELETE ✔        ✔
2095
============================================= ===================================== ====== ======== ==========
2096

  
2097

  
2098 2126
List Images
2099
...........
2127
-----------
2100 2128

  
2101 2129
List all images accessible by the user
2102 2130

  
......
2160 2188
      <image attribute>: <value>,
2161 2189
      ...
2162 2190
      metadata: {
2163
        <image metadatum key>: <value>,
2191
        <image meta key>: <value>,
2164 2192
        ...
2165 2193
      },
2166 2194
      ...
......
2242 2270
  }
2243 2271

  
2244 2272
Get Image Details
2245
.................
2273
-----------------
2246 2274

  
2247 2275
Get the details of a specific image
2248 2276

  
......
2290 2318
    <image attribute>: <value>,
2291 2319
    ...
2292 2320
    metadata: {
2293
      <image metadatum key>: <value>
2321
      <image meta key>: <value>
2294 2322
    }
2295 2323
  }
2296 2324

  
......
2337 2365

  
2338 2366

  
2339 2367
Delete Image
2340
............
2368
------------
2341 2369

  
2342 2370
Delete an image, by changing its status from ``ACTIVE`` to ``DELETED``.
2343 2371

  
......
2381 2409
.. note:: In case of a 204 code, request body should be empty
2382 2410

  
2383 2411
List Image Metadata
2384
...................
2412
-------------------
2385 2413

  
2386 2414
.. rubric:: Request
2387 2415

  
......
2394 2422
* **image-id** is the identifier of the virtual image
2395 2423

  
2396 2424
|
2397

  
2398 2425
==============  ========================= ======== ==========
2399 2426
Request Header  Value                     Cyclades OS/Compute
2400 2427
==============  ========================= ======== ==========
......
2424 2451
Response body content::
2425 2452

  
2426 2453
  metadata: {
2427
    <metadatum key>: <value>,
2454
    <meta key>: <value>,
2428 2455
  ...
2429 2456
  }
2430 2457

  
......
2449 2476
.. note:: In OS/Compute API  the ``values`` level is missing from the response.
2450 2477

  
2451 2478
Update Image Metadata
2452
.....................
2479
---------------------
2453 2480

  
2454 2481
In Cyclades API, setting new metadata and updating the values of existing ones
2455 2482
is achieved using one type of request (POST), while in OS/Compute API two
......
2474 2501
* **image-id** is the identifier of the virtual image
2475 2502

  
2476 2503
|
2477

  
2478 2504
==============  ========================= ======== ==========
2479 2505
Request Header  Value                     Cyclades OS/Compute
2480 2506
==============  ========================= ======== ==========
......
2494 2520
Request body content::
2495 2521

  
2496 2522
  metadata: {
2497
    <metadatum key>: <value>,
2523
    <meta key>: <value>,
2498 2524
    ...
2499 2525
  }
2500 2526

  
......
2513 2539
400 (Bad Request)           Malformed request or image id
2514 2540
401 (Unauthorized)          Missing or expired user token
2515 2541
403 (Forbidden)             Not allowed to modify this image
2516
404 (Not Found)             Image or metadatum key not found
2542
404 (Not Found)             Image or meta key not found
2517 2543
413 (OverLimit)             Maximum number of metadata exceeded
2518 2544
500 (Internal Server Error) The request cannot be completed because of an
2519 2545
\                           internal error
......
2546 2572
    }
2547 2573
  }
2548 2574

  
2549
Get Image Metadatum
2550
...................
2575
Get Image Metadata
2576
------------------
2551 2577

  
2552 2578
.. rubric:: Request
2553 2579

  
......
2559 2585

  
2560 2586
* **image-id** is the identifier of the image
2561 2587

  
2562
* **key** is the key of a matadatum ``key``:``value`` pair
2588
* **key** is the key of a mata ``key``:``value`` pair
2563 2589

  
2564 2590
|
2565 2591

  
......
2582 2608
400 (Bad Request)           Malformed request or image id
2583 2609
401 (Unauthorized)          Missing or expired user token
2584 2610
403 (Forbidden)             Not allowed to access this information
2585
404 (Not Found)             Metadatum key not found
2611
404 (Not Found)             Meta key not found
2586 2612
500 (Internal Server Error) The request cannot be completed because of an
2587 2613
\                           internal error
2588 2614
503 (Service Unavailable)   The server is not currently available
......
2592 2618

  
2593 2619
  metadata: {<key>: <value>}
2594 2620

  
2595
*Example Get Image Metadatum Item: JSON*
2621
*Example Get Image Metadata Item: JSON*
2596 2622

  
2597 2623
.. code-block:: javascript
2598 2624

  
......
2600 2626

  
2601 2627
.. note:: In OS/Compute, ``metadata`` is ``meta``
2602 2628

  
2603
Update Image Metadatum
2604
......................
2629
Update Image Metadata
2630
---------------------
2605 2631

  
2606 2632
.. rubric:: Request
2607 2633

  
......
2613 2639

  
2614 2640
* **image-id** is the identifier of the image
2615 2641

  
2616
* **key** is the key of a matadatum ``key``:``value`` pair
2642
* **key** is the key of a matadata ``key``:``value`` pair
2617 2643

  
2618 2644
|
2619 2645

  
......
2639 2665

  
2640 2666
  metadata: {<key>: <value>}
2641 2667

  
2642
*Example Update Image Metadatum Item Request: JSON*
2668
*Example Update Image Metadata Item Request: JSON*
2643 2669

  
2644 2670
.. code-block:: javascript
2645 2671

  
......
2654 2680
400 (Bad Request)           Malformed request or image id
2655 2681
401 (Unauthorized)          Missing or expired user token
2656 2682
403 (Forbidden)             Not allowed to modify this image
2657
404 (Not Found)             Metadatum key not found
2683
404 (Not Found)             Metadata key not found
2658 2684
413 (OverLimit)             Maximum number of metadata exceeded
2659 2685
500 (Internal Server Error) The request cannot be completed because of an
2660 2686
\                           internal error
......
2665 2691

  
2666 2692
  metadata: {<key>: <value>}
2667 2693

  
2668
*Example Update Image Metadatum Item Response: JSON*
2694
*Example Update Image Metadata Item Response: JSON*
2669 2695

  
2670 2696
.. code-block:: javascript
2671 2697

  
2672 2698
  {"metadata": {"os": "Kubuntu"}}
2673 2699

  
2674
Delete Image Metadatum
2675
......................
2700
Delete Image Metadata
2701
---------------------
2676 2702

  
2677
Delete an image metadatum by its key.
2703
Delete an image metadata by its key.
2678 2704

  
2679 2705
.. rubric:: Request
2680 2706

  
......
2686 2712

  
2687 2713
* **image-id** is the identifier of the image
2688 2714

  
2689
* **key** is the key of a matadatum ``key``:``value`` pair
2715
* **key** is the key of a mata ``key``:``value`` pair
2690 2716

  
2691 2717
|
2692

  
2693 2718
==============  ========================= ======== ==========
2694 2719
Request Header  Value                     Cyclades OS/Compute
2695 2720
==============  ========================= ======== ==========
......
2709 2734
400 (Bad Request)           Malformed image ID
2710 2735
401 (Unauthorized)          Missing or expired user token
2711 2736
403 (Forbidden)             Not allowed to modify this image
2712
404 (Not Found)             Metadatum key not found
2737
404 (Not Found)             Metadata key not found
2713 2738
500 (Internal Server Error) The request cannot be completed because of an
2714 2739
\                           internal error
2715 2740
503 (Service Unavailable)   The server is not currently available
......
2717 2742

  
2718 2743
.. note:: In case of a 204 code, the response body should be empty.
2719 2744

  
2720
Networks
2721
--------
2722

  
2723
============= ======== ==========
2724
BASE URI      Cyclades OS/Compute
2725
============= ======== ==========
2726
``/networks`` ✔        **✘**
2727
============= ======== ==========
2728

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

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

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

  
2743
=============================================== ================================= ======
2744
Description                                     URI                               Method
2745
=============================================== ================================= ======
2746
`List <#list-networks>`_                        ``/networks``                     GET
2747
\                                               ``/networks/detail``              GET
2748
`Create <#create-network>`_                     ``/networks``                     POST
2749
`Get details <#get-network-details>`_           ``/networks/<network-id>``        GET
2750
`Rename <#rename-network>`_                     ``/networks/<network-id>``        PUT
2751
`Delete <#delete-network>`_                     ``/networks/<network-id>``        DELETE
2752
`Connect <#connect-network-to-server>`_         ``/networks/<network-id>/action`` POST
2753
`Disconnect <#disconnect-network-from-server>`_ ``/networks/<network-id>/action`` POST
2754
=============================================== ================================= ======
2755

  
2756

  
2757
List Networks
2758
.............
2745
Index of Attributes
2746
-------------------
2759 2747

  
2760
This operation lists the networks associated with a users account
2748
.. _server-ref:
2761 2749

  
2762
.. rubric:: Request
2750
Server Attributes
2751
.................
2763 2752

  
2764
==================== ======
2765
URI                  Method
2766
==================== ======
2767
``/networks``        GET
2768
``/networks/detail`` GET
2769
==================== ======
2753
=================== ======== ==========
2754
Server attribute    Cyclades OS/Compute
2755
=================== ======== ==========
2756
id                  ✔        ✔
2757
name                ✔        ✔
2758
addresses           ✔        ✔
2759
links               ✔        ✔
2760
image               ✔        ✔
2761
flavor              ✔        ✔
2762
user_id             ✔        ✔
2763
tenant_id           ✔        ✔
2764
accessIPv4          ✔        ✔
2765
accessIPv6          ✔        ✔
2766
progress            ✔        ✔
2767
status              ✔        ✔
2768
updated             ✔        ✔
2769
hostId              ✔        ✔
2770
created             ✔        ✔
2771
adminPass           ✔        ✔
2772
metadata            ✔        ✔
2773
suspended           ✔        **✘**
2774
security_groups     ✔        **✘**
2775
attachments         ✔        **✘**
2776
config_drive        ✔        **✘**
2777
SNF:fqdn            ✔        **✘**
2778
key_name            ✔        **✘**
2779
SNF:port_forwarding ✔        **✘**
2780
SNF:task_state      ✔        **✘**
2781
diagnostics         ✔        **✘**
2782
deleted             ✔        **✘**
2783
=================== ======== ==========
2784

  
2785
* **addresses** Networks related to this server. All information in this field
2786
  is redundant, since it can be infered from the ``attachments`` field, but
2787
  it is used for compatibility with OS/Computet
2788

  
2789
* **user_id** The UUID of the owner of the virtual server
2790

  
2791
* **tenant_id** The UUID of the main project for this user
2792

  
2793
* *hostId*, **accessIPv4** and **accessIPv6** are always empty and are used for
2794
  compatibility with OS/Compute
2795

  
2796
* **progress** Shows the building progress of a virtual server. After the server
2797
  is built, it is always ``100``
2770 2798

  
2771
|
2799
* **status** values are described `here <#status-ref>`_
2772 2800

  
2773
==============  =========================
2774
Request Header  Value
2775
==============  =========================
2776
X-Auth-Token    User authentication token
2777
==============  =========================
2801
* **updated** and **created** are date-formated
2778 2802

  
2779
.. note:: Request parameters should be empty
2803
* **adminPass** is shown only once (in ``create server`` response). This
2804
  information is not preserved in a clear text form, so it is not recoverable
2780 2805

  
2781
.. note:: Request body should be empty
2806
* **suspended** is True only if the server is suspended by the cloud
2807
  administrations or policy
2782 2808

  
2783
.. rubric:: Response
2809
* **progress** is a number between 0 and 100 and reflects the server building
2810
  status
2784 2811

  
2785
=========================== =====================
2786
Return Code                 Description
2787
=========================== =====================
2788
204 (OK)                    Request succeeded
2789
304 (Not Modified)
2790
400 (Bad Request)           Malformed network id
2791
401 (Unauthorized)          Missing or expired user token
2792
404 (Not Found)             Network not found
2793
409 (Build In Progress)     Server is not ready yet
2794
500 (Internal Server Error) The request cannot be completed because of an
2795
\                           internal error
2796
503 (Service Unavailable)   Action not supported or service currently
2797
\                           unavailable
2798
=========================== =====================
2799

  
2800
Response body content::
2801

  
2802
  networks: [
2803
    {
2804
      <network attribute>: <value>,
2805
      ...
2806
    },
2807
    ...
2808
  }
2809

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

  
2813
*Example Networks List Response: JSON (regular)*
2814

  
2815
.. code-block:: javascript
2816

  
2817
  {
2818
    "networks": [
2819
      {
2820
        "id": "1",
2821
        "name": "public",
2822
        "links": [
2823
            {
2824
                "href": "https://example.org/compute/v2.0/networks/1",
2825
                "rel": "self"
2826
            }, {
2827
                "href": "https://example.org/compute/v2.0/networks/1",
2828
                "rel": "bookmark"
2829
            }
2830
        ], 
2831
      },
2832
      {
2833
        "id": "2",
2834
        "name": "my private network",
2835
        "links": [
2836
            {
2837
                "href": "https://example.org/compute/v2.0/networks/2",
2838
                "rel": "self"
2839
            }, {
2840
                "href": "https://example.org/compute/v2.0/networks/2",
2841
                "rel": "bookmark"
2842
            }
2843
        ],
2844
      }
2845
    ]
2846
  }
2847

  
2848
*Example Networks List Response: JSON (detail)*
2849

  
2850
.. code-block:: javascript
2851

  
2852
  {
2853
    "networks": [
2854
      {
2855
        "id": "1",
2856
        "name": "public",
2857
        "links": [
2858
            {
2859
                "href": "https://example.org/compute/v2.0/networks/1", 
2860
                "rel": "self"
2861
            }, 
2862
            {
2863
                "href": "https://example.org/compute/v2.0/networks/1", 
2864
                "rel": "bookmark"
2865
            }
2866
        ], 
2867
        "created": "2011-04-20T15:31:08.199640+00:00",
2868
        "updated": "2011-05-06T12:47:05.582679+00:00",
2869
        "attachments": ["nic-42-0", "nic-73-0"]
2870
      }, {
2871
        "id": 2,
2872
        "name": "my private network",
2873
        "links": [
2874
            {
2875
                "href": "https://example.org/compute/v2.0/networks/2", 
2876
                "rel": "self"
2877
            }, 
2878
            {
2879
                "href": "https://example.org/compute/v2.0/networks/2", 
2880
                "rel": "bookmark"
2881
            }
2882
        ], 
2883
        "created": "2011-04-20T14:32:08.199640+00:00",
2884
        "updated": "2011-05-06T11:40:05.582679+00:00",
2885
        "attachments": ["nic-42-2", "nic-7-3"]
2886
      }
2887
    ]
2888
  }
2889

  
2890

  
2891
Create Network
2892
..............
2893

  
2894
This operation asynchronously provisions a new network.
2895

  
2896
.. rubric:: Request
2897

  
2898
==================== ======
2899
URI                  Method
2900
==================== ======
2901
``/networks``        POST
2902
==================== ======
2903

  
2904
|
2905

  
2906
==============  =========================
2907
Request Header  Value
2908
==============  =========================
2909
X-Auth-Token    User authentication token
2910
Content-Type    Type or request body     
2911
Content-Length  Length of request body   
2912
==============  =========================
2913

  
2914
**Example Request Headers**::
2915

  
2916
  X-Auth-Token:   z31uRXUn1LZy45p1r7V==
2917
  Content-Type:   application/json
2918
  Content-Length: 60
2919

  
2920
.. note:: Request parameters should be empty
2921

  
2922
Request body content::
2923

  
2924
  network: {
2925
    <request attribute>: <value>,
2926
    ...
2927
  }
2928

  
2929
================== ======================= ======== =======
2930
Request Attributes Description             Required Default
2931
================== ======================= ======== =======
2932
name               Network name            ✔
2933
type               Network type            ✔
2934
dhcp               If use DHCP             **✘**    True
2935
cidr               IPv4 CIDR               **✘**    192.168.1.0/2
2936
cidr6              IPv6 CDIR               **✘**    null
2937
gateway            IPv4 gateway address    **✘**    null
2938
gateway6           IPv6 gateway address    **✘**    null
2939
public             If a public network     **✘**    False
2940
================== ======================= ======== =======
2941

  
2942
* **name** is a string
2943

  
2944
* **type** can be CUSTOM, IP_LESS_ROUTED, MAC_FILTERED, PHYSICAL_VLAN
2945

  
2946
* **dhcp** and **public** are flags
2947

  
2948
* **cidr**, and **gateway** are IPv4 addresses
2949

  
2950
* **cidr6**, and **gateway6** are IPv6 addresses
2951

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

  
2954
*Example Create Network Request Body: JSON*
2955

  
2956
.. code-block:: javascript
2957

  
2958
  {"network": {"name": "private_net", "type": "MAC_FILTERED"}}
2959

  
2960
.. rubric:: Response
2961

  
2962
=========================== =====================
2963
Return Code                 Description
2964
=========================== =====================
2965
202 (OK)                    Request succeeded
2966
400 (Bad Request)           Malformed network id or request
2967
401 (Unauthorized)          Missing or expired user token
2968
403 (Forbidden)             Public network is forbidden
2969
404 (Not Found)             Network not found
2970
413 (Over Limit)            Reached networks limit
2971
415 (Bad Media Type)        Bad network type
2972
500 (Internal Server Error) The request cannot be completed because of an
2973
\                           internal error
2974
503 (Service Unavailable)   Failed to allocated network resources
2975
=========================== =====================
2976

  
2977
Response body content::
2978

  
2979
  network: {
2980
    <network attribute>: <value>,
2981
    ...
2982
  }
2983

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

  
2986
*Example Create Network Response: JSON*
2987

  
2988
.. code-block:: javascript
2989

  
2990
  {
2991
    "network": {
2992
      "status": "PENDING",
2993
      "updated": "2013-04-25T13:31:17.165237+00:00",
2994
      "name": "my private network",
2995
      "links": [
2996
        {
2997
            "href": "https://example.org/compute/v2.0/networks/6567",
2998
            "rel": "self"
2999
        }, {
3000
            "href": "https://example.org/compute/v2.0/networks/6567",
3001
            "rel": "bookmark"
3002
        }
3003
      ], 
3004
      "created": "2013-04-25T13:31:17.165088+00:00",
3005
      "cidr6": null,
3006
      "id": "6567",
3007
      "gateway6": null,
3008
      "public": false,
3009
      "dhcp": false,
3010
      "cidr": "192.168.1.0/24",
3011
      "type": "MAC_FILTERED",
3012
      "gateway": null,
3013
      "attachments": []
3014
    }
3015
  }
3016

  
3017
Get Network Details
3018
...................
3019

  
3020
.. rubric:: Request
3021

  
3022
========================== ======
3023
URI                        Method
3024
========================== ======
3025
``/networks/<network-id>`` GET
3026
========================== ======
3027

  
3028
* **network-id** is the identifier of the network
3029

  
3030
|
3031

  
3032
==============  =========================
3033
Request Header  Value
3034
==============  =========================
3035
X-Auth-Token    User authentication token
3036
==============  =========================
3037

  
3038
.. note:: Request parameters should be empty
3039

  
3040
.. note:: Request body should be empty
3041

  
3042
.. rubric:: Response
3043

  
3044
=========================== =====================
3045
Return Code                 Description
3046
=========================== =====================
3047
200 (OK)                    Request succeeded
3048
400 (Bad Request)           Malformed request or network id
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff