Statistics
| Branch: | Tag: | Revision:

root / docs / network-api-guide.rst @ a3d2b515

History | View | Annotate | Download (47.2 kB)

1
.. _network-api-guide:
2

    
3
Cyclades/Network API Guide
4
^^^^^^^^^^^^^^^^^^^^^^^^^^
5

    
6
Introduction
7
============
8

    
9
The Network Service of `Synnefo <http://www.synnefo.org>`_ is implemented as
10
part of Cyclades. It exposes the OpenStack `Networking ("Neutron") API
11
<http://api.openstack.org/api-ref-networking.html>`_ and some
12
`extensions <file:///home/saxtouri/src/synnefo/docs/_build/html/network-api-guide.html>`_
13
with minor modifications if needed.
14

    
15
This document's goals are:
16

    
17
* Define the Cyclades/Network REST API
18
* Clarify the differences between Cyclades/Network and OpenStack Neutron
19

    
20
API Operations
21
==============
22

    
23
.. rubric:: Networks
24
===================================== ========================== ====== ======== ======= ==========
25
Description                           URI                        Method Cyclades/Network OS/Neutron
26
===================================== ========================== ====== ================ ==========
27
`List <#list-networks>`_              ``/networks``              GET    ✔                ✔
28
`Get details <#get-network-details>`_ ``/networks/<network-id>`` GET    ✔                ✔
29
`Create <#create-network>`_           ``/networks``              POST   ✔                ✔
30
Bulk creation                         ``/networks``              POST   **✘**            ✔
31
`Update <#update-network>`_           ``/networks/<network-id>`` PUT    ✔                ✔
32
`Delete <#delete-network>`_           ``/networks/<network id>`` DELETE ✔                ✔
33
===================================== ========================== ====== ================ ==========
34

    
35
.. rubric:: Subnets
36
==================================== ======================== ====== ======== ======= ==========
37
Description                          URI                      Method Cyclades/Network OS/Neutron
38
==================================== ======================== ====== ================ ==========
39
`List <#list-subnets>`_              ``/subnets``             GET    ✔                ✔
40
`Get details <#get-subnet-details>`_ ``/subnets/<subnet-id>`` GET    ✔                ✔
41
`Create <#create-subnet>`_           ``/subnets``             POST   ✔                ✔
42
Bulk creation                        ``/subnets``             POST   **✘**            ✔
43
`Update <#update-subnet>`_           ``/subnets/<subnet-id>`` PUT    ✔                ✔
44
Delete                               ``/subnets/<subnet-id>`` DELETE **✘**            ✔
45
==================================== ======================== ====== ================ ==========
46

    
47
.. rubric:: Ports
48
================================== ==================== ====== ======== ======= ==========
49
Description                        URI                  Method Cyclades/Network OS/Neutron
50
================================== ==================== ====== ================ ==========
51
`List <#list-ports>`_              ``/ports``           GET    ✔                ✔
52
`Get details <#get-port-details>`_ ``/ports/<port-id>`` GET    ✔                ✔
53
`Create <#create-port>`_           ``/ports``           POST   ✔                ✔
54
Bulk creation                      ``/ports``           POST   **✘**            ✔
55
`Update <#update-port>`_           ``/ports/<port-id>`` PUT    ✔                ✔
56
`Delete <#delete-port>`_           ``/ports/<port id>`` DELETE ✔                ✔
57
================================== ==================== ====== ================ ==========
58

    
59
.. rubric:: Floating IPs
60
========================================= ================================ ====== ================ ==========
61
Description                               URI                              Method Cyclades/Network OS/Neutron Extensions
62
========================================= ================================ ====== ================ ==========
63
`List <#list-floating-ips>`_              ``/floatingips``                 GET    ✔                ✔
64
`Get details <#get-floating-ip-details>`_ ``/floatingips/<floatingip-id>`` GET    ✔                ✔
65
`Create <#create-floating-ip>`_           ``/floatingips``                 POST   ✔                ✔
66
Update                                    ``/floatingips/<floatingip-id>`` PUT    **✘**            ✔
67
`Delete <#delete-floating-ip>`_           ``/floatingips/<floatingip id>`` DELETE ✔                ✔
68
========================================= ================================ ====== ================ ==========
69

    
70
List networks
71
-------------
72

    
73
List networks accessible by the user
74

    
75
.. rubric:: Request
76

    
77
============= ====== ================ ==========
78
URI           Method Cyclades/Network OS/Neutron
79
============= ====== ================ ==========
80
``/networks`` GET    ✔                ✔
81
============= ====== ================ ==========
82

    
83
|
84
==============  ========================= ================ ==========
85
Request Header  Value                     Cyclades/Network OS/Neutron
86
==============  ========================= ================ ==========
87
X-Auth-Token    User authentication token required         required
88
==============  ========================= ================ ==========
89

    
90
.. rubric:: Response
91

    
92
=========================== =====================
93
Return Code                 Description
94
=========================== =====================
95
200 (OK)                    Request succeeded
96
401 (Unauthorized)          Missing or expired user token
97
=========================== =====================
98

    
99

    
100
Response body contents::
101

    
102
  networks: [
103
    {
104
      <network attribute>: <value>,
105
      ...
106
    }, ...
107
  ]
108

    
109
The attributes of a network are listed `here <#network-ref>`_
110

    
111
*Example List Networks: JSON*
112

    
113
.. code-block:: javascript
114

    
115
  GET https://example.org/network/v2.0/networks
116

    
117

    
118
  {
119
    "networks": [
120
      {
121
        "id": 2718
122
        "name": "Public IPv6 Network"
123
        "status": "ACTIVE"
124
        "router:externa"l: true
125
        "updated": "2013-12-18T11:11:12.272389+00:00"
126
        "user_id": None
127
        "links":[
128
          {
129
            "href": "https://example.org/network/v2.0/networks/2718"
130
            "rel": "self"
131
          }, {
132
            "href": "https://example.org/network/v2.0/networks/2718"
133
            "rel": "bookmark"
134
          }
135
        ]
136
        "created": "2013-12-17T17:15:48.617049+00:00"
137
        "tenant_id": None
138
        "admin_state_up": true
139
        "SNF:floating_ip_pool": false
140
        "public": true
141
        "subnets":[
142
          28
143
        ]
144
        "type": "IP_LESS_ROUTED",
145
        "public": true
146
      }, {
147
        "id": "3141", 
148
        "name": "My Private Network", 
149
        "status": "ACTIVE", 
150
        "router:external": false, 
151
        "updated": "2014-02-13T09:40:05.195945+00:00", 
152
        "user_id": "s0m3-u5e7-1d", 
153
        "links": [
154
          {
155
              "href": "https://example.org/network/v2.0/networks/3141", 
156
              "rel": "self"
157
          }, 
158
          {
159
              "href": "https://example.org/network/v2.0/networks/3141", 
160
              "rel": "bookmark"
161
          }
162
        ], 
163
        "created": "2014-02-13T09:40:05.101008+00:00", 
164
        "tenant_id": "s0m3-u5e7-1d", 
165
        "admin_state_up": true, 
166
        "type": "MAC_FILTERED", 
167
        "subnets": [], 
168
        "SNF:floating_ip_pool": false,
169
        "public": false
170
      }
171
    ]
172
  }
173

    
174

    
175
Get network details
176
-------------------
177

    
178
.. rubric:: Request
179

    
180
========================== ====== ================ ==========
181
URI                        Method Cyclades/Network OS/Neutron
182
========================== ====== ================ ==========
183
``/networks/<network id>`` GET    ✔                ✔
184
========================== ====== ================ ==========
185

    
186
|
187
==============  ========================= ================ ==========
188
Request Header  Value                     Cyclades/Network OS/Neutron
189
==============  ========================= ================ ==========
190
X-Auth-Token    User authentication token required         required
191
==============  ========================= ================ ==========
192

    
193
.. rubric:: Response
194

    
195
=========================== =====================
196
Return Code                 Description
197
=========================== =====================
198
200 (OK)                    Request succeeded
199
401 (Unauthorized)          Missing or expired user token
200
404 (itemNoFound)           Network not found
201
=========================== =====================
202

    
203
Response body contents::
204

    
205
  network: {
206
    <network attribute>: <value>,
207
    ...
208
  }
209

    
210
The attributes of a network are listed `here <#network-ref>`_
211

    
212
*Example Get Network Details: JSON*
213

    
214
.. code-block:: javascript
215

    
216
  GET https://example.org/network/v2.0/networks/3141
217

    
218

    
219
  {
220
    "network": {
221
      "id": "3141", 
222
      "name": "My Private Network", 
223
      "status": "ACTIVE", 
224
      "router:external": false, 
225
      "updated": "2014-02-13T09:40:05.195945+00:00", 
226
      "user_id": "s0m3-u5e7-1d", 
227
      "links": [
228
        {
229
            "href": "https://example.org/network/v2.0/networks/3141", 
230
            "rel": "self"
231
        }, 
232
        {
233
            "href": "https://example.org/network/v2.0/networks/3141", 
234
            "rel": "bookmark"
235
        }
236
      ], 
237
      "created": "2014-02-13T09:40:05.101008+00:00", 
238
      "tenant_id": "s0m3-u5e7-1d", 
239
      "admin_state_up": true, 
240
      "type": "MAC_FILTERED", 
241
      "subnets": [], 
242
      "SNF:floating_ip_pool": false,
243
      "public": false
244
    }
245
  }
246

    
247
Create network
248
--------------
249

    
250
.. rubric:: Request
251

    
252
============= ====== ================ ==========
253
URI           Method Cyclades/Network OS/Neutron
254
============= ====== ================ ==========
255
``/networks`` POST   ✔                ✔
256
============= ====== ================ ==========
257

    
258
|
259
==============  ========================= ================ ==========
260
Request Header  Value                     Cyclades/Network OS/Neutron
261
==============  ========================= ================ ==========
262
X-Auth-Token    User authentication token required         required
263
Content-Type    Type or request body      required         required
264
Content-Length  Length of request body    required         required
265
==============  ========================= ================ ==========
266

    
267
Request body contents::
268

    
269
  network: {
270
    <network attribute>: <value>,
271
    ...
272
  }
273

    
274
================= ================ ==========
275
Network Attribute Cyclades/Network OS/Neutron
276
================= ================ ==========
277
type              required         **✘**
278
name              ✔                ✔
279
admin_state_up    **✘**            ✔
280
shared            **✘**            ✔
281
tenand_id         **✘**            ✔
282
================= ================ ==========
283

    
284
* **type** Valid values are the same as in ``network_type`` of
285
  `a network <#network-ref>`_.
286

    
287
* **name** a string
288

    
289
* **admin_state_up**, **shared** and **tenantd_id** are accepted by
290
  Cyclades/Network, but they are ignored
291

    
292
.. rubric:: Response
293

    
294
=========================== =====================
295
Return Code                 Description
296
=========================== =====================
297
201 (OK)                    Network created
298
400 (BadRequest)            Invalid request body (invalid or missing type)
299
401 (Unauthorized)          Missing or expired user token
300
404 (itemNoFound)           Network not found
301
=========================== =====================
302

    
303
In case of success, the response has the same format is in
304
`get network details <#get-network-details>`_.
305

    
306
Update network
307
--------------
308

    
309
.. rubric:: Request
310

    
311
========================== ====== ================ ==========
312
URI                        Method Cyclades/Network OS/Neutron
313
========================== ====== ================ ==========
314
``/networks/<network id>`` PUT    ✔                ✔
315
========================== ====== ================ ==========
316

    
317
|
318

    
319
==============  ========================= ================ ==========
320
Request Header  Value                     Cyclades/Network OS/Neutron
321
==============  ========================= ================ ==========
322
X-Auth-Token    User authentication token required         required
323
Content-Type    Type or request body      required         required
324
Content-Length  Length of request body    required         required
325
==============  ========================= ================ ==========
326

    
327
Request body contents::
328

    
329
  network: {
330
    <network attribute>: <value>,
331
    ...
332
  }
333

    
334
================= ================ ==========
335
Network Attribute Cyclades/Network OS/Neutron
336
================= ================ ==========
337
name              ✔                ✔
338
network_id        **✘**            ✔
339
admin_state_up    **✘**            ✔
340
shared            **✘**            ✔
341
tenand_id         **✘**            ✔
342
================= ================ ==========
343

    
344
* **name** a string
345

    
346
* **network_id**, **admin_state_up**, **shared** and **tenantd_id** are
347
  accepted by   Cyclades/Network, but they are ignored
348

    
349
.. rubric:: Response
350

    
351
=========================== =====================
352
Return Code                 Description
353
=========================== =====================
354
200 (OK)                    Network is updated
355
401 (Unauthorized)          Missing or expired user token
356
403 (Forbidden)             You are not the owner of the network
357
404 (itemNoFound)           Network not found
358
=========================== =====================
359

    
360
In case of success, the response has the same format is in
361
`get network details <#get-network-details>`_ containing the updated values.
362

    
363
Delete network
364
--------------
365

    
366
.. rubric:: Request
367

    
368
========================== ====== ================ ==========
369
URI                        Method Cyclades/Network OS/Neutron
370
========================== ====== ================ ==========
371
``/networks/<network id>`` DELETE ✔                ✔
372
========================== ====== ================ ==========
373
|
374
==============  ========================= ================ ==========
375
Request Header  Value                     Cyclades/Network OS/Neutron
376
==============  ========================= ================ ==========
377
X-Auth-Token    User authentication token required         required
378
==============  ========================= ================ ==========
379

    
380
.. rubric:: Response
381

    
382
=========================== =====================
383
Return Code                 Description
384
=========================== =====================
385
204 (OK)                    Network is deleted
386
401 (Unauthorized)          Missing or expired user token
387
404 (itemNoFound)           Network not found
388
409 (Conflict)              The network is being used
389
=========================== =====================
390

    
391
.. note:: *409 (Confict)* is raised when there are ports connected to the
392
  network or floating IPs reserved from its pool. The subnets that are
393
  connected to it, though, are automatically deleted upon network deletion.
394

    
395
List subnets
396
------------
397

    
398
List subnets of networks accessible by the user
399

    
400
.. rubric:: Request
401

    
402
============ ====== ================ ==========
403
URI          Method Cyclades/Network OS/Neutron
404
============ ====== ================ ==========
405
``/subnets`` GET    ✔                ✔
406
============ ====== ================ ==========
407

    
408
|
409
============== ========================= ================ ==========
410
Request Header Value                     Cyclades/Network OS/Neutron
411
============== ========================= ================ ==========
412
X-Auth-Token   User authentication token required         required
413
============== ========================= ================ ==========
414

    
415
.. rubric:: Response
416

    
417
=========================== =====================
418
Return Code                 Description
419
=========================== =====================
420
200 (OK)                    Request succeeded
421
401 (Unauthorized)          Missing or expired user token
422
=========================== =====================
423

    
424
Response body contents::
425

    
426
  subnets: [
427
    {
428
      <subnet attribute>: <value>,
429
      ...
430
    }, ...
431
  ]
432

    
433
The attributes of a subnet are listed `here <#subnet-ref>`_
434

    
435
*Example List subnets: JSON*
436

    
437
.. code-block:: javascript
438

    
439
  GET https://example.org/network/v2.0/subnets
440

    
441
  {
442
    "subnets": [
443
      {
444
        "user_id": null, 
445
        "name": "IPv6 Subnet of Network 2718", 
446
        "links": [
447
            {
448
                "href": "https://example.org/network/v2.0/subnets/8172", 
449
                "rel": "self"
450
            }, 
451
            {
452
                "href": "https://example.org/network/v2.0/subnets/8172", 
453
                "rel": "bookmark"
454
            }
455
        ], 
456
        "network_id": "2718", 
457
        "tenant_id": null, 
458
        "dns_nameservers": [], 
459
        "enable_slaac": true, 
460
        "public": true, 
461
        "allocation_pools": [], 
462
        "host_routes": [], 
463
        "ip_version": 6, 
464
        "gateway_ip": "2001:123:4abc:5678::9", 
465
        "cidr": "2001:876:5cba:4321::/64", 
466
        "enable_dhcp": true, 
467
        "id": "8172"
468
      }, {
469
        "user_id": "s0m3-u5e7-1d", 
470
        "name": "IPv6 Subnet of Network 3141", 
471
        "links": [
472
            {
473
                "href": "https://example.org/network/v2.0/subnets/1413", 
474
                "rel": "self"
475
            }, 
476
            {
477
                "href": "https://example.org/network/v2.0/subnets/1413", 
478
                "rel": "bookmark"
479
            }
480
        ], 
481
        "network_id": "3141", 
482
        "tenant_id": "s0m3-u5e7-1d", 
483
        "dns_nameservers": [], 
484
        "enable_slaac": false, 
485
        "public": false, 
486
        "allocation_pools": [], 
487
        "host_routes": [], 
488
        "ip_version": 6, 
489
        "gateway_ip": "2001:321:4abc:8765::9",
490
        "cidr": "2001:678:5cba:1234::/64", 
491
        "enable_dhcp": true, 
492
        "id": "1413"
493
      }
494
    ]
495
  }
496

    
497

    
498
Get subnet details
499
----------------
500

    
501
.. rubric:: Request
502

    
503
======================== ====== ================ ==========
504
URI                      Method Cyclades/Network OS/Neutron
505
======================== ====== ================ ==========
506
``/subnets/<subnet id>`` GET    ✔                ✔
507
======================== ====== ================ ==========
508

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

    
516
.. rubric:: Response
517

    
518
=========================== =====================
519
Return Code                 Description
520
=========================== =====================
521
201 (OK)                    Request succeeded
522
401 (Unauthorized)          Missing or expired user token
523
404 (itemNoFound)           Subnet not found
524
=========================== =====================
525

    
526
Response body contents::
527

    
528
  subnet: {
529
    <subnet attribute>: <value>,
530
    ...
531
  }
532

    
533
The attributes of a subnet are listed `here <#subnet-ref>`_
534

    
535
*Example Get subnet Details: JSON*
536

    
537
.. code-block:: javascript
538

    
539
  GET https://example.org/network/v2.0/subnets/1413
540

    
541

    
542
  {
543
    "subnet": {
544
        "user_id": "s0m3-u5e7-1d", 
545
        "name": "IPv6 Subnet of Network 3141", 
546
        "links": [
547
            {
548
                "href": "https://example.org/network/v2.0/subnets/1413", 
549
                "rel": "self"
550
            }, 
551
            {
552
                "href": "https://example.org/network/v2.0/subnets/1413", 
553
                "rel": "bookmark"
554
            }
555
        ], 
556
        "network_id": "3141", 
557
        "tenant_id": "s0m3-u5e7-1d", 
558
        "dns_nameservers": [], 
559
        "enable_slaac": false, 
560
        "public": false, 
561
        "allocation_pools": [], 
562
        "host_routes": [], 
563
        "ip_version": 6, 
564
        "gateway_ip": "2001:321:4abc:8765::9",
565
        "cidr": "2001:678:5cba:1234::/64", 
566
        "enable_dhcp": true, 
567
        "id": "1413"
568
      }
569
  }
570

    
571
Create subnet
572
--------------
573

    
574
.. rubric:: Request
575

    
576
========== ====== ================ ==========
577
URI        Method Cyclades/Network OS/Neutron
578
========== ====== ================ ==========
579
``/subnets`` POST   ✔              ✔
580
========== ====== ================ ==========
581

    
582
|
583
==============  ========================= ================ ==========
584
Request Header  Value                     Cyclades/Network OS/Neutron
585
==============  ========================= ================ ==========
586
X-Auth-Token    User authentication token required         required
587
Content-Type    Type or request body      required         required
588
Content-Length  Length of request body    required         required
589
==============  ========================= ================ ==========
590

    
591
Request body contents::
592

    
593
  subnet: {
594
    <subnet attribute>: <value>,
595
    ...
596
  }
597

    
598
================= ================ ==========
599
Subnet Attribute  Cyclades/Network OS/Neutron
600
================= ================ ==========
601
network_id        required         required
602
cidr              required         required
603
fixed_ips         ✔                ✔
604
name              ✔                ✔
605
tenand_id         **✘**            ✔
606
allocation_pools  ✔                ✔
607
gateway_ip        ✔                ✔
608
ip_version        ✔                ✔
609
id                **✘**            ✔
610
enable_dhcp       ✔                ✔
611
================= ================ ==========
612

    
613
* All the attributes are explained `here <#subnet-ref>`_
614

    
615
* **ip_version** must be set to 6 if ``cidr`` is an IPc6 subnet
616

    
617
* **tenand_id** and **id** are accepted but ignored
618

    
619
.. rubric:: Response
620

    
621
=========================== =====================
622
Return Code                 Description
623
=========================== =====================
624
201 (OK)                    Network created
625
400 (BadRequest)            Invalid request body (missing network_id or cidr)
626
401 (Unauthorized)          Missing or expired user token
627
403 (Forbidden)             Insufficient permissions
628
404 (itemNoFound)           Network not found
629
409 (Conflict)              Allocation pools overlap with themselves or gateway
630
=========================== =====================
631

    
632
In case of success, the response has the same format is in
633
`get subnet details <#get-subnet-details>`_.
634

    
635
Update subnet
636
-------------
637

    
638
.. rubric:: Request
639

    
640
======================== ====== ================ ==========
641
URI                      Method Cyclades/Network OS/Neutron
642
======================== ====== ================ ==========
643
``/subnets/<subnet id>`` PUT    ✔                ✔
644
======================== ====== ================ ==========
645

    
646
|
647
============== ========================= ================ ==========
648
Request Header Value                     Cyclades/Network OS/Neutron
649
============== ========================= ================ ==========
650
X-Auth-Token   User authentication token required         required
651
Content-Type   Type or request body      required         required
652
Content-Length Length of request body    required         required
653
============== ========================= ================ ==========
654

    
655
Request body contents::
656

    
657
  subnet: {
658
    <subnet attribute>: <value>,
659
    ...
660
  }
661

    
662
================= ================ ==========
663
Subnet Attribute  Cyclades/Network OS/Neutron
664
================= ================ ==========
665
network_id        **✘**            ✔
666
cidr              **✘**            ✔
667
fixed_ips         **✘**            ✔
668
name              ✔                ✔
669
tenand_id         **✘**            ✔
670
allocation_pools  **✘**            ✔
671
gateway_ip        **✘**            ✔
672
ip_version        **✘**            ✔
673
id                **✘**            ✔
674
enable_dhcp       **✘**            ✔
675
================= ================ ==========
676

    
677
.. rubric:: Response
678

    
679
=========================== =====================
680
Return Code                 Description
681
=========================== =====================
682
200 (OK)                    Network is updated
683
400 (BadRequest)            Field is not modifiable
684
401 (Unauthorized)          Missing or expired user token
685
403 (Forbidden)             You are not the owner of this subnet
686
404 (itemNoFound)           Subnet not found
687
=========================== =====================
688

    
689
In case of success, the response has the same format as in
690
`get subnet details <#get-subnet-details>`_ containing the updated values.
691

    
692
List ports
693
----------
694

    
695
List ports connected on servers and networks accessible by the user
696

    
697
.. rubric:: Request
698

    
699
========== ====== ================ ==========
700
URI        Method Cyclades/Network OS/Neutron
701
========== ====== ================ ==========
702
``/ports`` GET    ✔                ✔
703
========== ====== ================ ==========
704

    
705
|
706
============== ========================= ================ ==========
707
Request Header Value                     Cyclades/Network OS/Neutron
708
============== ========================= ================ ==========
709
X-Auth-Token   User authentication token required         required
710
============== ========================= ================ ==========
711

    
712
.. rubric:: Response
713

    
714
=========================== =====================
715
Return Code                 Description
716
=========================== =====================
717
200 (OK)                    Request succeeded
718
401 (Unauthorized)          Missing or expired user token
719
=========================== =====================
720

    
721

    
722
Response body contents::
723

    
724
  ports: [
725
    {
726
      <port attribute>: <value>,
727
      ...
728
    }, ...
729
  ]
730

    
731
The attributes of a port are listed `here <#port-ref>`_
732

    
733
*Example List Ports: JSON*
734

    
735
.. code-block:: javascript
736

    
737
  GET https://example.org/network/v2.0/ports
738

    
739
  {
740
    "ports": [
741
      {
742
        "status": "ACTIVE", 
743
        "updated": "2014-02-12T08:32:41.785217+00:00", 
744
        "user_id": "s0m3-u5e7-1d", 
745
        "name": "Port to public network",
746
        "links": [
747
            {
748
                "href": "https://example.org/network/v2.0/ports/18", 
749
                "rel": "self"
750
            }, 
751
            {
752
                "href": "https://example.org/network/v2.0/ports/18", 
753
                "rel": "bookmark"
754
            }
755
        ], 
756
        "admin_state_up": true,
757
        "network_id": "2718",
758
        "tenant_id": "s0m3-u5e7-1d",
759
        "created": "2014-02-12T08:31:37.782907+00:00",
760
        "device_owner": "vm",
761
        "mac_address": "aa:01:02:6c:34:ab",
762
        "fixed_ips": [
763
            {
764
                "subnet": "28", 
765
                "ip_address": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab"
766
            }
767
        ], 
768
        "id": "18", 
769
        "security_groups": [], 
770
        "device_id": "42"
771
      }, {
772
        "status": "ACTIVE", 
773
        "updated": "2014-02-15T08:32:41.785217+00:00", 
774
        "user_id": "s0m3-u5e7-1d", 
775
        "name": "Port to public network",
776
        "links": [
777
            {
778
                "href": "https://example.org/network/v2.0/ports/19", 
779
                "rel": "self"
780
            }, 
781
            {
782
                "href": "https://example.org/network/v2.0/ports/19", 
783
                "rel": "bookmark"
784
            }
785
        ], 
786
        "admin_state_up": true,
787
        "network_id": "2719",
788
        "tenant_id": "s0m3-u5e7-1d",
789
        "created": "2014-02-15T08:31:37.782907+00:00",
790
        "device_owner": "vm",
791
        "mac_address": "aa:00:0c:6d:34:bb",
792
        "fixed_ips": [
793
            {
794
                "subnet": "29", 
795
                "ip_address": "192.168.1.2"
796
            }
797
        ], 
798
        "id": "19", 
799
        "security_groups": [], 
800
        "device_id": "42"
801
      }
802
    ]
803
  }
804

    
805

    
806
Get port details
807
----------------
808

    
809
.. rubric:: Request
810

    
811
==================== ====== ================ ==========
812
URI                  Method Cyclades/Network OS/Neutron
813
==================== ====== ================ ==========
814
``/ports/<port id>`` GET    ✔                ✔
815
==================== ====== ================ ==========
816

    
817
|
818
============== ========================= ================ ==========
819
Request Header Value                     Cyclades/Network OS/Neutron
820
============== ========================= ================ ==========
821
X-Auth-Token   User authentication token required         required
822
============== ========================= ================ ==========
823

    
824
.. rubric:: Response
825

    
826
=========================== =====================
827
Return Code                 Description
828
=========================== =====================
829
200 (OK)                    Request succeeded
830
401 (Unauthorized)          Missing or expired user token
831
404 (itemNoFound)           Port not found
832
=========================== =====================
833

    
834
Response body contents::
835

    
836
  port: {
837
    <port attribute>: <value>,
838
    ...
839
  }
840

    
841
The attributes of a port are listed `here <#port-ref>`_
842

    
843
*Example Get Port Details: JSON*
844

    
845
.. code-block:: javascript
846

    
847
  GET https://example.org/network/v2.0/ports/18
848

    
849

    
850
  {
851
    "port": {
852
      "status": "ACTIVE", 
853
      "updated": "2014-02-12T08:32:41.785217+00:00", 
854
      "user_id": "s0m3-u5e7-1d", 
855
      "name": "Port to public network",
856
      "links": [
857
        {
858
            "href": "https://example.org/network/v2.0/ports/18", 
859
            "rel": "self"
860
        }, 
861
        {
862
            "href": "https://example.org/network/v2.0/ports/18", 
863
            "rel": "bookmark"
864
        }
865
      ], 
866
      "admin_state_up": true,
867
      "network_id": "2718",
868
      "tenant_id": "s0m3-u5e7-1d",
869
      "created": "2014-02-12T08:31:37.782907+00:00",
870
      "device_owner": "vm",
871
      "mac_address": "aa:01:02:6c:34:ab",
872
      "fixed_ips": [
873
        {
874
            "subnet": "28", 
875
            "ip_address": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab"
876
        }
877
      ], 
878
      "id": "18", 
879
      "security_groups": [], 
880
      "device_id": "42"
881
      }
882
  }
883

    
884
Create port
885
--------------
886

    
887
.. rubric:: Request
888

    
889
========== ====== ================ ==========
890
URI        Method Cyclades/Network OS/Neutron
891
========== ====== ================ ==========
892
``/ports`` POST   ✔              ✔
893
========== ====== ================ ==========
894

    
895
|
896
==============  ========================= ================ ==========
897
Request Header  Value                     Cyclades/Network OS/Neutron
898
==============  ========================= ================ ==========
899
X-Auth-Token    User authentication token required         required
900
Content-Type    Type or request body      required         required
901
Content-Length  Length of request body    required         required
902
==============  ========================= ================ ==========
903

    
904
Request body contents::
905

    
906
  port: {
907
    <port attribute>: <value>,
908
    ...
909
  }
910

    
911
=============== ================ ==========
912
Port Attribute  Cyclades/Network OS/Neutron
913
=============== ================ ==========
914
network_id      required         required
915
device_id       ✔                **✘**
916
fixed_ips       ✔                ✔
917
name            ✔                ✔
918
security_groups ✔                ✔
919
admin_state_up  **✘**            ✔
920
mac_address     **✘**            ✔
921
tenand_id       **✘**            ✔
922
=============== ================ ==========
923

    
924
* **network_id** is the uuid of the network this port is connected to
925

    
926
* **device_id** is the id of the device (i.e. server or router) this port is
927
  connected to
928

    
929
* **fixed_ips** is a list of IP items. Each IP item is a dictionary containing
930
  an ``ip_address`` field. The value must be the IPv4 address of a floating IP
931
  which is reserved from the pool of the network with ``network_id``, for the
932
  current user
933

    
934
* **name** a string
935

    
936
* **security_groups** is a list of security group IDs
937

    
938
* **admin_state_up**, **mac_address** and **tenantd_id** are accepted by
939
  Cyclades/Network, but they are ignored
940

    
941
.. rubric:: Response
942

    
943
=========================== =====================
944
Return Code                 Description
945
=========================== =====================
946
201 (OK)                    Network created
947
400 (BadRequest)            Invalid request body (missing network_id)
948
401 (Unauthorized)          Missing or expired user token
949
403 (Forbidden)             Insufficient permissions
950
404 (itemNoFound)           Network not found
951
503 (macGenerationFailure)  Mac address generation failed
952
=========================== =====================
953

    
954
In case of success, the response has the same format is in
955
`get port details <#get-port-details>`_.
956

    
957
Update port
958
-----------
959

    
960
.. rubric:: Request
961

    
962
========================== ====== ================ ==========
963
URI                        Method Cyclades/Network OS/Neutron
964
========================== ====== ================ ==========
965
``/ports/<port id>`` PUT    ✔                ✔
966
========================== ====== ================ ==========
967

    
968
|
969

    
970
============== ========================= ================ ==========
971
Request Header Value                     Cyclades/Network OS/Neutron
972
============== ========================= ================ ==========
973
X-Auth-Token   User authentication token required         required
974
Content-Type   Type or request body      required         required
975
Content-Length Length of request body    required         required
976
============== ========================= ================ ==========
977

    
978
Request body contents::
979

    
980
  port: {
981
    <port attribute>: <value>,
982
    ...
983
  }
984

    
985
=============== ================ ==========
986
Port Attribute  Cyclades/Network OS/Neutron
987
=============== ================ ==========
988
name            ✔                ✔
989
network_id      **✘**            ✔
990
port_id         **✘**            ✔
991
fixed_ips       **✘**            ✔
992
security_groups **✘**            ✔
993
admin_state_up  **✘**            ✔
994
mac_address     **✘**            ✔
995
tenand_id       **✘**            ✔
996
=============== ================ ==========
997

    
998

    
999
* **name** a string
1000

    
1001
* all other attributes are accepted but ignored
1002

    
1003
.. rubric:: Response
1004

    
1005
=========================== =====================
1006
Return Code                 Description
1007
=========================== =====================
1008
200 (OK)                    Network is updated
1009
401 (Unauthorized)          Missing or expired user token
1010
403 (Forbidden)             You are not the owner of the network
1011
404 (itemNoFound)           Network not found
1012
=========================== =====================
1013

    
1014
In case of success, the response has the same format as in
1015
`get port details <#get-port-details>`_ containing the updated values.
1016

    
1017
Delete port
1018
-----------
1019

    
1020
Delete a port
1021

    
1022
.. rubric:: Request
1023

    
1024
========================== ====== ================ ==========
1025
URI                        Method Cyclades/Network OS/Neutron
1026
========================== ====== ================ ==========
1027
``/ports/<port id>``       DELETE ✔                ✔
1028
========================== ====== ================ ==========
1029

    
1030
|
1031
==============  ========================= ================ ==========
1032
Request Header  Value                     Cyclades/Network OS/Neutron
1033
==============  ========================= ================ ==========
1034
X-Auth-Token    User authentication token required         required
1035
==============  ========================= ================ ==========
1036

    
1037
.. rubric:: Response
1038

    
1039
=========================== =====================
1040
Return Code                 Description
1041
=========================== =====================
1042
204 (OK)                    Port is being deleted
1043
401 (Unauthorized)          Missing or expired user token
1044
404 (itemNoFound)           Port not found
1045
=========================== =====================
1046

    
1047
List floating ips
1048
-----------------
1049

    
1050
List the floating ips which are reserved by the user
1051

    
1052
.. rubric:: Request
1053

    
1054
================ ====== ================ ==========
1055
URI              Method Cyclades/Network OS/Neutron Extensions
1056
================ ====== ================ ==========
1057
``/floatingips`` GET    ✔                ✔
1058
================ ====== ================ ==========
1059

    
1060
|
1061
============== ========================= ================ ==========
1062
Request Header Value                     Cyclades/Network OS/Neutron Extensions
1063
============== ========================= ================ ==========
1064
X-Auth-Token   User authentication token required         required
1065
============== ========================= ================ ==========
1066

    
1067
.. rubric:: Response
1068

    
1069
=========================== =====================
1070
Return Code                 Description
1071
=========================== =====================
1072
200 (OK)                    Request succeeded
1073
401 (Unauthorized)          Missing or expired user token
1074
=========================== =====================
1075

    
1076
Response body contents::
1077

    
1078
  floatingips: [
1079
    {
1080
      <floating ip attribute>: <value>,
1081
      ...
1082
    }, ...
1083
  ]
1084

    
1085
The attributes of a floating ip are listed `here <#floating-ip-ref>`_
1086

    
1087
*Example List Floating IPs: JSON*
1088

    
1089
.. code-block:: javascript
1090

    
1091
  GET https://example.org/network/v2.0/floatingips
1092

    
1093
  {
1094
    "floatingips": [
1095
      {
1096
        "instance_id": 42
1097
        "floating_network_id": 2719
1098
        "fixed_ip_address": None
1099
        "floating_ip_address": "192.168.1.2"
1100
        "port_id": 19
1101
      }, 
1102
      {
1103
        "instance_id": 84
1104
        "floating_network_id": 4178
1105
        "fixed_ip_address": None
1106
        "floating_ip_address": 192.168.1.3
1107
        "port_id": 38
1108
      }
1109
    ]
1110
  }
1111

    
1112
Get floating ip details
1113
-----------------------
1114

    
1115
.. rubric:: Request
1116

    
1117
======================== ====== ================ =====================
1118
URI                      Method Cyclades/Network OS/Neutron Extensions
1119
======================== ====== ================ =====================
1120
``/floatingips/<ip-id>`` GET    ✔                ✔
1121
======================== ====== ================ =====================
1122

    
1123
|
1124
============== ========================= ================ ==========
1125
Request Header Value                     Cyclades/Network OS/Neutron Extensions
1126
============== ========================= ================ ==========
1127
X-Auth-Token   User authentication token required         required
1128
============== ========================= ================ ==========
1129

    
1130
.. rubric:: Response
1131

    
1132
=========================== =====================
1133
Return Code                 Description
1134
=========================== =====================
1135
201 (OK)                    Request succeeded
1136
401 (Unauthorized)          Missing or expired user token
1137
404 (itemNoFound)           Floating IP not found
1138
=========================== =====================
1139

    
1140
Response body contents::
1141

    
1142
  floatingip: {
1143
    <floating ip attribute>: <value>,
1144
    ...
1145
  }
1146

    
1147
The attributes of a floating ip are listed `here <#floating-ip-ref>`_
1148

    
1149
*Example Get Floating IP Details: JSON*
1150

    
1151
.. code-block:: javascript
1152

    
1153
  GET https://example.org/network/v2.0/floatingips/19
1154

    
1155

    
1156
  {
1157
    "floatingip": {
1158
      "instance_id": 42
1159
      "floating_network_id": 2719
1160
      "fixed_ip_address": None
1161
      "floating_ip_address": "192.168.1.2"
1162
      "port_i"d: 19
1163
    }
1164
  }
1165

    
1166
Create floating ip
1167
------------------
1168

    
1169
.. rubric:: Request
1170

    
1171
================ ====== ================ =====================
1172
URI              Method Cyclades/Network OS/Neutron Extensions
1173
================ ====== ================ =====================
1174
``/floatingips`` POST   ✔              ✔
1175
================ ====== ================ =====================
1176

    
1177
|
1178

    
1179
============== ========================= ================ =====================
1180
Request Header Value                     Cyclades/Network OS/Neutron Extensions
1181
============== ========================= ================ =====================
1182
X-Auth-Token   User authentication token required         required
1183
Content-Type   Type or request body      required         required
1184
Content-Length Length of request body    required         required
1185
============== ========================= ================ =====================
1186

    
1187
Request body contents::
1188

    
1189
  floating ip: {
1190
    <floating ip attribute>: <value>,
1191
    ...
1192
  }
1193

    
1194
===================== ================ ==========
1195
Floating IP Attribute Cyclades/Network OS/Neutron Extensions
1196
===================== ================ ==========
1197
floating network_id   required         required
1198
floating_ip_address   ✔                ✔
1199
port_id               **✘**            ✔
1200
fixed_ip_address      **✘**            ✔
1201
===================== ================ ==========
1202

    
1203
* All the attributes are explained `here <#floating-ip-ref>`_
1204

    
1205
.. rubric:: Response
1206

    
1207
=========================== =====================
1208
Return Code                 Description
1209
=========================== =====================
1210
201 (OK)                    Network created
1211
400 (BadRequest)            Invalid request body (missing floating_network_id)
1212
401 (Unauthorized)          Missing or expired user token
1213
409 (Conflict)              Insufficient resources
1214
=========================== =====================
1215

    
1216
In case of success, the response has the same format is in
1217
`get floating ip details <#get-floating-ip-details>`_.
1218

    
1219
Delete floating ip
1220
------------------
1221

    
1222
.. rubric:: Request
1223

    
1224
================================ ====== ================ =====================
1225
URI                              Method Cyclades/Network OS/Neutron Extensions
1226
================================ ====== ================ =====================
1227
``/floatingips/<floatingip-id>`` DELETE ✔                ✔
1228
================================ ====== ================ =====================
1229

    
1230
|
1231
==============  ========================= ================ ==========
1232
Request Header  Value                     Cyclades/Network OS/Neutron Extensions
1233
==============  ========================= ================ ==========
1234
X-Auth-Token    User authentication token required         required
1235
==============  ========================= ================ ==========
1236

    
1237
.. rubric:: Response
1238

    
1239
=========================== =====================
1240
Return Code                 Description
1241
=========================== =====================
1242
204 (OK)                    Floating IP is being deleted
1243
401 (Unauthorized)          Missing or expired user token
1244
404 (itemNoFound)           Floating IP not found
1245
=========================== =====================
1246

    
1247
Index of Attributes
1248
-------------------
1249

    
1250
.. _network-ref:
1251

    
1252
Network attributes
1253
..................
1254

    
1255
================== ================ ==========
1256
Network attributes Cyclades/Network OS/Neutron
1257
================== ================ ==========
1258
admin_state_up     ✔                ✔
1259
id                 ✔                ✔
1260
name               ✔                ✔
1261
shared             ✔                ✔
1262
public             ✔                **✘**
1263
status             ✔                ✔
1264
subnets            ✔                ✔
1265
tenant_id          ✔                ✔
1266
user_id            ✔                **✘**
1267
network_type       ✔                **✘**
1268
router:external    ✔                **✘**
1269
SNF:floating_ip    ✔                **✘**
1270
links              ✔                **✘**
1271
================== ================ ==========
1272

    
1273
* **admin_state_up** The administrative state of the network (true, false)
1274
* **shared** Used for compatibility with OS/Neutron and has the same value as
1275
    public
1276
* **public** If the network is publicly accessible (true, false)
1277
* **status** ACTIVE, DOWN, BUILD, ERROR, SNF:DRAINED
1278
    The later means that no new ports or floating IPs can be created from this
1279
    network
1280
* **tenant_id** Used for compatibility with OS/Neutron and has the same value
1281
    as user_id
1282
* **user_id** The owner of the network if private or None if public
1283
* **network_type** MAC_FILTERED, IP_LESS_ROUTED, PHYSICAL_VLAN
1284
* **router:external**  Whether the network is connected to an external router
1285
    (true, false)
1286

    
1287
.. _subnet-ref:
1288

    
1289
Subnet attributes
1290
.................
1291

    
1292
================= ================ ==========
1293
Subnet attributes Cyclades/Network OS/Neutron
1294
================= ================ ==========
1295
id                ✔                ✔
1296
name              ✔                ✔
1297
network_id        ✔                ✔
1298
ip_version        ✔                ✔
1299
cidr              ✔                ✔
1300
gateway_ip        ✔                ✔
1301
enable_dhcp       ✔                ✔
1302
allocation_pools  ✔                ✔
1303
tenant_id         ✔                ✔
1304
dns_nameservers   ✔                ✔
1305
host_routes       ✔                ✔
1306
user_id           ✔                **✘**
1307
enable_slaac      ✔                **✘**
1308
links             ✔                **✘**
1309
================= ================ ==========
1310

    
1311
* **id** The UUID for the subnet
1312
* **name** A human readable name
1313
* **network_id** The ID of the network associated with this subnet
1314
* **ip_version** The IP version (4, 6) of the subnet (default is 4)
1315
* **cidr** CIDR represents IP range for this subnet, based on the IP version
1316
* **gateway_ip** Default gateway used by devices in this subnet. If not
1317
    specified the service will be the first available IP address. Tto get no
1318
    gateway, set to None
1319
* **enable_dhcp** Wheather nfdhcpd is enabled for this subnet (true, false)
1320
* **enable_slaac** Whether SLAAC is enabled for this subnet (true, false)
1321
* **allocation_pools(CR)** Subranges of cidr available for dynamic allocation.
1322
    List of dictionaries of the form:
1323
    [{“start”: “192.168.2.0”, “end”: 192.168.2.10”}, ...]
1324
* **user_id** The UUID of the network owner, None if the network is public
1325
* **tenant_id** Used for compatibility with OpenStack/Neutron, always equal to
1326
    ``user_id``
1327
* **host_routes** Routes that should be used by devices with IPs from this
1328
    subnet (list)
1329
* **dns_nameservers** Used for compatibility with OpenStack/Neutron
1330

    
1331
.. _port-ref:
1332

    
1333
Port attributes
1334
...............
1335

    
1336
==================== ================ ==========
1337
Port attributes      Cyclades/Network OS/Neutron
1338
==================== ================ ==========
1339
id                   ✔                ✔
1340
name                 ✔                ✔
1341
status               ✔                ✔
1342
admin_state_up       ✔                ✔
1343
network_id           ✔                ✔
1344
tenant_id            ✔                ✔
1345
mac_address          ✔                ✔
1346
fixed_ips            ✔                ✔
1347
device_id            ✔                ✔
1348
device_owner         ✔                ✔
1349
security_groups      ✔                ✔
1350
port_filter          **✘**            ✔
1351
binding:vif_type     **✘**            ✔
1352
binding:capabilities **✘**            ✔
1353
user_id              ✔                **✘**
1354
links                ✔                **✘**
1355
==================== ================ ==========
1356

    
1357
* **status** ACTIVE, DOWN, BUILD, ERROR
1358
* **admin_state_up** The administrative state of the network (true, false). If
1359
    false, the network does not forward packets
1360
* **network_id**  UUID of the attached network
1361
* **user_id** The UUID of the owner of the network, or None if the network is
1362
    public
1363
* **tenant_id** Used for compatibility with OpenStack/Neutron and always has
1364
    the same value as the user_id
1365
* **device_owner** ID of the entity using this port. e.g.,
1366
    network:router, network:router_gateway
1367
* **fixed_ips** IP information for the port (list of dicts). Each IP item
1368
    (dictionary) consists of a ``subnet`` and an ``ip_address`` field.
1369
* **device_id** The ID of the device that uses this port i.e., a virtual server
1370
    or a router
1371

    
1372
* **security_groups** List of security group IDs associated with this port
1373

    
1374
.. _floating-ip-ref:
1375

    
1376
Floating ip attributes
1377
......................
1378

    
1379
====================== ================ ==========
1380
Floating ip attributes Cyclades/Network OS/Neutron Extensions
1381
====================== ================ ==========
1382
id                     ✔                ✔
1383
floating_network_id    ✔                ✔
1384
floating_ip_address    ✔                ✔
1385
fixed_ip_address       ✔                ✔
1386
port_id                ✔                ✔
1387
user_id                ✔                **✘**
1388
tenant_id              ✔                ✔
1389
instance_id            ✔                **✘**
1390
router_id              ✔                ✔
1391
====================== ================ ==========
1392

    
1393

    
1394
* **id** The UUID for the floating IP
1395
* **floating_network_id** The UUID of the external network associated to this
1396
    floating IP is associated.
1397
* **floating_ip_address** The IPv4 address of the floating IP
1398
* **fixed_ip_address** Used for compatibility, always None
1399
* **port_id** The port where this IP is attached, if any
1400
* **instance_id** The device using this floating IP, if any
1401
* **user_id** The UUID of the owner of the floating IP
1402
* **tenant_id:** Used for compatibility, always equal ``to user_id``
1403
* **router_id** The ID of the router, if any