Synnefo

.. _cyclades-api-guide:

API Guide

*********

`Cyclades <cyclades.html>`_ is the Compute Service of `Synnefo

<http://www.synnefo.org>`_. The Cyclades API tries to be as close to the

`OpenStack Compute API v2

<http://docs.openstack.org/api/openstack-compute/2/content>`_ as possible.

This document's goals are:

* Define the Cyclades/Compute REST API

* Clarify the differences between Cyclades and OpenStack/Compute

Users and developers who wish to access Cyclades through its REST API are

advised to use the `kamaki <http://docs.dev.grnet.gr/kamaki>`_ command-line

client and associated python library, instead of making direct calls.

Overview

========

* OpenStack does not define if requests for invalid URLs should return 404 or a

* Fault. We return a BadRequest Fault.

* OpenStack does not define if requests with a wrong HTTP method should return

* 405 or a Fault. We return a BadRequest Fault.

General API Information

=======================

Authentication

--------------

All requests use the same authentication method: an ``X-Auth-Token`` header is

passed to the servive, which is used to authenticate the user and retrieve user

related information. No other user details are passed through HTTP.

Efficient Polling with the Changes-Since Parameter

--------------------------------------------------

* Effectively limit support of the changes-since parameter in **List Servers**

  and **List Images**.

* Assume that garbage collection of deleted servers will only affect servers

  deleted ``POLL_TIME`` seconds (default: 3600) in the past or earlier. Else

  loose the information of a server getting deleted.

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

Limitations

-----------

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

* Cyclades only supports JSON Requests and JSON/XML Responses. XML Requests are

  currently not supported.

* Optional content compression support is currently not supported.

* To prevent abuse, HTTP sessions have a timeout of 20 seconds before being

  closed.

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

* Pagination is currently not supported.

* Cached responses are currently not supported.

* Limits are currently not supported.

* Extensions are currently not supported.

API Operations

==============

Servers

-------

=================================================== ========================================= ====== ======== ==========

Description                                         URI                                       Method Cyclades OS/Compute

=================================================== ========================================= ====== ======== ==========

`List <#list-servers>`_                             ``/servers``                              GET    ✔        ✔

\                                                   ``/servers/detail``                       GET    ✔        ✔

`Create <#create-server>`_                          ``/servers``                              POST   ✔        ✔

`Get Stats <#get-server-stats>`_                    ``/servers/<server-id>/stats``            GET    ✔        **✘**

`Get Diagnostics <#get-server-diagnostics>`_        ``/servers/<server-id>/diagnostics``      GET    ✔        **✘**

`Get Details <#get-server-details>`_                ``/servers/<server id>``                  GET    ✔        ✔

`Rename <#rename-server>`_                          ``/servers/<server id>``                  PUT    ✔        ✔

`Delete <#delete-server>`_                          ``/servers/<server id>``                  DELETE ✔        ✔

`List Addresses <#list-server-addresses>`_          ``/servers/<server id>/ips``              GET    ✔        ✔

`Get NICs by Net <#get-server-nics-by-network>`_    ``/servers/<server id>/ips/<network id>`` GET    ✔        ✔

`List Metadata <#list-server-metadata>`_            ``/servers/<server-id>/meta``             GET    ✔        **✘**

\                                                   ``/servers/<server-id>/metadata``         GET    **✘**    ✔

`Update Metadata <#set-update-server-metadata>`_    ``/servers/<server-id>/meta``             POST    ✔       **✘**

\                                                   ``/servers/<server-id>/metadata``         PUT    **✘**    ✔

\                                                   ``/servers/<server-id>/metadata``         POST   **✘**    ✔

`Get Meta Item <#get-server-metadata-item>`_        ``/servers/<server-id>/meta/<key>``       GET    ✔        **✘**

\                                                   ``/servers/<server-id>/metadata/<key>``   GET    **✘**    ✔

`Update Meta Item <#update-server-metadatum-item>`_ ``/servers/<server-id>/meta/<key>``       PUT    ✔        **✘**

\                                                   ``/servers/<server-id>/metadata/<key>``   PUT    **✘**    ✔

`Delete Meta Item <#delete-server-metadatum>`_      ``/servers/<server-id>/meta/<key>``       DELETE ✔        **✘**

\                                                   ``/servers/<server-id>/metadata/<key>``   DELETE **✘**    ✔

=================================================== ========================================= ====== ======== ==========

List Servers

............

List all virtual servers owned by the user.

.. rubric:: Request

=================== ====== ======== ==========

URI                 Method Cyclades OS/Compute

=================== ====== ======== ==========

``/servers``        GET    ✔        ✔

``/servers/detail`` GET    ✔        ✔

=================== ====== ======== ==========

* Both requests return a list of servers. The first returns just ``id`` and

  ``name``, while the second returns the full collections of server

  attributes.

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

==============  ========================= ======== ==========

|

================= =================================== ======== ==========

Request Parameter Value                               Cyclades OS/Compute

================= =================================== ======== ==========

json              Respond in json                     default  **✘**

xml               Respond in xml                      ✔        **✘**

changes-since     Servers delete since that timestamp ✔        ✔

image             Image reference                     **✘**    ✔

flavor            VM flavor reference                 **✘**    ✔

server            Server flavor reference             **✘**    ✔

status            Server status                       **✘**    ✔

marker            Last list last ID                   **✘**    ✔

limit             Page size                           **✘**    ✔

================= =================================== ======== ==========

* **json** and **xml** parameters are mutually exclusive. If none supported,

the response will be formated in json.

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

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

.. note:: Request body should be empty

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

200 (OK)                    Request succeeded

304 (No servers since date) Can be returned if ``changes-since`` is given

400 (Bad Request)           Invalid or malformed ``changes-since`` parameter

401 (Unauthorized)          Missing or expired user token

403 (Forbidden)             User is not allowed to perform this operation

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   The server is not currently available

=========================== =====================

|

Response body contents::

  servers: [

    {

      <server attribute>: <value>,

      ...

    }, ...

  ]

================= ====================== ======== ==========

Server Attributes Description            Cyclades OS/Compute

================= ====================== ======== ==========

id                The server id          ✔        ✔

name              The server name        ✔        ✔

hostId            Server playground      empty    ✔

created           Creation date          ✔        ✔

updated           Creation date          ✔        ✔

flavorRef         The flavor id          ✔        **✘**

flavor            The flavor id          **✘**    ✔

imageRef          The image id           ✔        **✘**

image             The image id           **✘**    ✔

progress          Build progress         ✔        ✔

status            Server status          ✔        ✔

attachments       Network interfaces     ✔        **✘**

addresses         Network interfaces     **✘**    ✔

metadata          Server custom metadata ✔        ✔

================= ====================== ======== ==========

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

  compatibility

* **progress** is changing while the server is building up and has values

  between 0 and 100. When it reaches 100 the server is built.

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

* **metadata** are custom key:value pairs used to specify various attributes of

  the VM (e.g. OS, super user, etc.)

* **attachments** in Cyclades are lists of network interfaces (nics).

  **Attachments** are different to OS/Compute's **addresses**. The former is a

  list of the server's `network interface connections <#nic-ref>`_ while the

  later is just a list of networks. Thus, a Cyclades virtual server may be

  connected to the same network through more than one distinct network

  interfaces (e.g. server 43 is connected to network 101 with nic-43-1 and

  nic-43-2 in the example bellow).

* **Network Interfaces (NICs)** contain information about a server's connection

  to a network. Each NIC is identified by an id of the form

  nic-<server-id>-<ordinal-number>. More details can be found `here

  <#nic-ref>`_.

*Example List Servers: JSON*

.. code-block:: javascript

  {

    "servers":

      {"values": [

        {

          "attachments": {

            "values": [

              {

                "id": "nic-42-0",

                "network_id": "101",

                "mac_address": "aa:00:00:49:2e:7e",

                "firewallProfile": "DISABLED",

                "ipv4": "192.168.4.5",

                "ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5b"

              }

            ]

          },

          "created': '2011-04-19T10:18:52.085737+00:00',

          "flavorRef": "1",

          "hostId": "",

          "id": "42",

          "imageRef": "3",

          "metadata": {"values": {"foo": "bar"}},

          "name": "My Server",

          "status": "ACTIVE",

          "updated": "2011-05-29T14:07:07.037602+00:00"

        }, {

          "attachments": {

            "values": [

              {

                "id": "nic-43-0",

                "mac_address": "aa:00:00:91:2f:df",

                "network_id": "1",

                "ipv4": "192.168.32.2"

              }, {

                "id": "nic-43-1",

                "network_id": "101",

                "mac_address": "aa:00:00:49:2g:7f",

                "firewallProfile": "DISABLED",

                "ipv4": "192.168.32.6",

                "ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5c'

              }, {

                "id": "nic-43-2",

                "network_id": "101",

                "mac_address": "aa:00:00:51:2h:7f",

                "firewallProfile": "DISABLED",

                "ipv4": "192.168.32.7",

                "ipv6": "2001:638:2eec:1222:a800:ff:fef5:3f5c"

              }

            ]

          },

          "created": "2011-05-02T20:51:08.527759+00:00",

          "flavorRef": "1",

          "hostId": "",

          "id": "43",

          "imageRef": "3",

          "name": "Other Server",

          "description": "A sample server to showcase server requests",

          "progress": "0",

          "status": "ACTIVE",

          "updated": "2011-05-29T14:59:11.267087+00:00"

        }

      ]

    }

  }

Create Server

.............

Create a new virtual server

.. rubric:: Request

============ ====== ======== ==========

URI          Method Cyclades OS/Compute

============ ====== ======== ==========

``/servers`` POST   ✔        ✔

============ ====== ======== ==========

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

Content-Type    Type or request body      required required

Content-Length  Length of request body    required required

==============  ========================= ======== ==========

*Example Request Headers*::

  X-Auth-Token:   z31uRXUn1LZy45p1r7V==

  Content-Type:   application/json

  Content-Length: 735

|

================= ===============

Request Parameter Value

================= ===============

json              Respond in json

xml               Respond in xml

================= ===============

Request body contents::

  server: {

      <server attribute>: <value>,

      ...

      personality: [

        {

          <personality attribute>: <value>,

          ...

        },

        ...

      ],

      ...

  }

=========== ==================== ======== ==========

Attributes  Description          Cyclades OS/Compute

=========== ==================== ======== ==========

name        The server name      ✔        ✔

imageRef    Image id             ✔        ✔

flavorRef   Resources flavor     ✔        ✔

personality Personality contents ✔        ✔

metadata    Custom metadata      ✔        ✔

=========== ==================== ======== ==========

* **name** can be any string

* **imageRed** and **flavorRed** should refer to existing images and hardware

  flavors accessible by the user

* **metadata** are ``key``:``value`` pairs of custom server-specific metadata.

  There are no semantic limitations.

* **personality** (optional) is a list of personality injections. A personality

  injection is a small set of changes to a virtual server. Each change modifies

  a file on the virtual server, by injecting some data in it. The injected data

  (``contents``) should exceed 10240 *bytes* in size and must be base64

  encoded. A personality injection contains the following attributes:

====================== =================== ======== ==========

Personality Attributes Description         Cyclades OS/Compute

====================== =================== ======== ==========

path                   File path on server ✔        ✔

contents               Data to inject      ✔        ✔

group                  User group          ✔        **✘**

mode                   File access mode    ✔        **✘**

owner                  File owner          ✔        **✘**

====================== =================== ======== ==========

*Example Create Server Request: JSON*

.. code-block:: javascript

  {

    "server": {

      "name": "My Server Name: Example Name",

      "imageRef": "da7a211f-...-f901ce81a3e6",

      "flavorRef": 289,

      "personality": [

        {

          "path": "/Users/myusername/personlities/example1.file",

          "contents": "some data to inject",

          "group": "remotely-set user group",

          "mode": "rw",

          "owner": "ausername"

        }, {

          "path": "/Users/myusername/personlities/example2.file",

          "contents": "some more data to inject",

          "group": "",

          "mode": "r",

          "owner": "anotherusername"

        }

      ],

      "metadata": {

        "values": {

          "EloquentDescription": "Example server with personality",

          "ShortDescription": "Trying VMs"

        }

      }

    }

  }

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

200 (OK)                    Request succeeded

400 (Bad Request)           Malformed request data

401 (Unauthorized)          Missing or expired user token

403 (Forbidden)             User is not allowed to perform this operation

404 (Not Found)             Image or Flavor not found

413 (Over Limit)            Exceeded some resource limit (#VMs, personality

size, etc.)

415 (Bad Media Type)        

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   No available backends or service currently

\                           unavailable

=========================== =====================

|

Response body contents::

  server: {

    <server attribute>: <value>,

    ...

  }

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

*Example Create Server Response: JSON*

.. code-block:: javascript

  {

    "server": {

      "id": 28130

      "status": "BUILD",

      "updated": "2013-04-10T13:52:18.140686+00:00",

      "hostId": "",

      "name": "My Server Name: Example Name",

      "imageRef": "da7a211f-...-f901ce81a3e6",

      "created": "2013-04-10T13:52:17.085402+00:00",

      "flavorRef": 289,

      "adminPass": "fKCqlZe2at",

      "suspended": false,

      "progress": 0

      "metadata": {

        "values": {

          "EloquentDescription": "Example server with personality",

          "ShortDescription": "Trying VMs"

        }

      }

    }

  }

*Example Create Server Response: XML*

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <server xmlns="http://docs.openstack.org/compute/api/v1.1"\

    xmlns:atom="http://www.w3.org/2005/Atom"

    id="1"

    status="BUILD"

    hostId="",

    name="My Server Name: Example Name"

    imageRef="da7a211f-...-f901ce81a3e6"

    created="2013-04-10T13:52:17.085402+00:00"

    flavorRef="289"

    adminPass="fKCqlZe2at"

    suspended="false"

    progress="0"

  />

Get Server Stats

................

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

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

.. rubric:: Request

============================== ====== ======== ==========

URI                            Method Cyclades OS/Compute

============================== ====== ======== ==========

``/servers/<server-id>/stats`` GET    ✔        **✘**

============================== ====== ======== ==========

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

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

==============  ========================= ======== ==========

|

================= ===============

Request Parameter Value          

================= ===============

json              Respond in json

xml               Respond in xml 

================= ===============

* **json** and **xml** parameters are mutually exclusive. If none supported,

the response will be formated in json.

.. note:: Request body should be empty

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

200 (OK)                    Request succeeded

400 (Bad Request)           Invalid server ID or Server deleted

401 (Unauthorized)          Missing or expired user token

403 (Forbidden)             Administratively suspended server

404 (Not Found)             Server not found

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   The server is not currently available

=========================== =====================

|

Response body contents::

  stats: {<parameter>: <value> }

============= ======================

Parameter     Description

============= ======================

serverRef     Server ID

refresh       Refresh frequency

cpuBar        Latest CPU load graph URL

cpuTimeSeries CPU load / time graph URL

netBar        Latest Network load graph URL

netTimeSeries Network load / time graph URL

============= ======================

* **refresh** is the recommended sampling rate

*Example Get Server Stats Response: JSON*

.. code-block:: javascript

  {

    "stats": {

      "serverRef": 1,

      "refresh": 60,

      "cpuBar": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-bar.png",

      "cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-ts.png",

      "netBar": "http://stats.okeanos.grnet.gr/b9a...048c/net-bar.png",

      "netTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/net-ts.png"

    }

  }

*Example Get Network Details Response: XML*

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <stats xmlns="http://docs.openstack.org/compute/api/v1.1"\

    xmlns:atom="http://www.w3.org/2005/Atom"

    serverRef="1"

    refresh="60"

    cpuBar="https://www.example.com/stats/snf-42/cpu-bar/",

    netTimeSeries="https://example.com/stats/snf-42/net-ts/",

    netBar="https://example.com/stats/snf-42/net-bar/",

    cpuTimeSeries="https://www.example.com/stats/snf-42/cpu-ts/"

  </stats>

Get Server Diagnostics

......................

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

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

.. rubric:: Request

==================================== ====== ======== ==========

URI                                  Method Cyclades OS/Compute

==================================== ====== ======== ==========

``/servers/<server-id>/diagnostics`` GET    ✔        **✘**

==================================== ====== ======== ==========

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

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

==============  ========================= ======== ==========

.. note:: Request parameters should be empty

.. note:: Request body should be empty

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

200 (OK)                    Request succeeded

400 (Bad Request)           Invalid server ID or Server deleted

401 (Unauthorized)          Missing or expired user token

403 (Forbidden)             Administratively suspended server

404 (Not Found)             Server not found

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   The server is not currently available

=========================== =====================

|

Response body contents::

  [

    {

      <diagnostic attribute}: <value>,

      ...

    }, {

      <diagnostic attribute}: <value>,

      ...

    },

    ...

  ]

==================== ===========

Diagnostic attribute Description

==================== ===========

level                Debug level

created              Log entry timestamp

source               Log source proccess

source_date          Log source date

message              Log description

details              Detailed log description

==================== ===========

*Example Get Server Diagnostics Response: JSON*

.. code-block:: javascript

  [

    {

      "level": "DEBUG",

      "created": "2013-04-09T15:25:53.965144+00:00",

      "source": "image-helper-task-start",

      "source_date": "2013-04-09T15:25:53.954695+00:00",

      "message": "FixPartitionTable",

      "details": null

    }, {

      "level": "DEBUG",

      "created": "2013-04-09T15:25:46.413718+00:00",

      "source": "image-info",

      "source_date": "2013-04-09T15:25:46.404477+00:00",

      "message": "Starting customization VM...",

      "details": null

    }, {

      "level": "DEBUG",

      "created": "2013-04-09T15:25:46.207038+00:00",

      "source": "image-info",

      "source_date": "2013-04-09T15:25:46.197183+00:00",

      "message": "Image copy finished.",

      "details": "All operations finished as they should. No errors reported."

    }

  ]

Get Server Details

..................

This operation returns detailed information for a virtual server

.. rubric:: Request

======================== ====== ======== ==========

URI                      Method Cyclades OS/Compute

======================== ====== ======== ==========

``/servers/<server id>`` GET    ✔        ✔

======================== ====== ======== ==========

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

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

==============  ========================= ======== ==========

.. note:: Request parameters should be empty

.. note:: Request body should be empty

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

200 (OK)                    Request succeeded

400 (Bad Request)           Malformed server id

401 (Unauthorized)          Missing or expired user token

403 (Forbidden)             Administratively suspended server

404 (Not Found)             Server not found

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   No available backends or service currently

\                           unavailable

=========================== =====================

|

Response body contents::

  server: {

    <server attribute>: <value>,

    ...

  }

================= ====================== ======== ==========

Server Attributes Description            Cyclades OS/Compute

================= ====================== ======== ==========

id                The server id          ✔        ✔

name              The server name        ✔        ✔

hostId            Server playground      empty    ✔

created           Creation date          ✔        ✔

updated           Creation date          ✔        ✔

flavorRef         The flavor id          ✔        **✘**

flavor            The flavor id          **✘**    ✔

imageRef          The image id           ✔        **✘**

image             The image id           **✘**    ✔

progress          Build progress         ✔        ✔

status            Server status          ✔        ✔

suspended         If server is suspended ✔        **✘**

attachments       Network interfaces     ✔        **✘**

addresses         Network interfaces     **✘**    ✔

metadata          Server custom metadata ✔        ✔

diagnostics       Diagnostic information ✔        **✘**

================= ====================== ======== ==========

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

  compatibility

* **progress** is changing while the server is building up and has values

  between 0 and 100. When it reaches 100 the server is built.

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

* **metadata** are custom key:value pairs used to specify various attributes of

  the VM (e.g. OS, super user, etc.)

* **attachments** in Cyclades are lists of network interfaces (NICs).

  **Attachments** are different to OS/Compute's **addresses**. The former is a

  list of the server's `network interface connections <#nic-ref>`_ while the

  later is just a list of networks. Thus, a Cyclades virtual server may be

  connected to the same network through more than one distinct network

  interfaces.

* **diagnostics** is a list of items that contain key:value information useful

  for diagnosing the server behavior and may be used by the administrators of

  deployed Synnefo setups.

*Example Details for server with id 42042: JSON*

.. code-block:: javascript

  {

    "server": {

      "id": 42042,

      "name": "My Example Server",

      "status": "ACTIVE",

      "updated": "2013-04-18T10:09:57.824266+00:00",

      "hostId": "",

      "imageRef": "926a1bc5-2d85-49d4-aebe-0fc127ed89b9",

      "created": "2013-04-18T10:06:58.288273+00:00",

      "flavorRef": 22,

      "attachments": {

        "values": [{

          "network_id": "1888",

          "mac_address": "aa:0c:f5:ad:16:41",

          "firewallProfile": "DISABLED",

          "ipv4": "83.212.112.56",

          "ipv6": "2001:648:2ffc:1119:a80c:f5ff:fead:1641",

          "id": "nic-42042-0"

        }]

      },

      "suspended": false,

      "diagnostics": [{

        "level": "DEBUG",

        "created": "2013-04-18T10:09:52.776920+00:00",

        "source": "image-info",

        "source_date": "2013-04-18T10:09:52.709791+00:00",

        "message": "Image customization finished successfully.",

        "details": null

      }],

      "progress": 100,

      "metadata": {

        "values": {"OS": "windows", "users": "Administrator"}

      }

    }

  }

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

Rename Server

.............

Modify the ``name`` attribute of a virtual server. OS/Compute API also features

the modification of IP addresses

.. rubric:: Response

======================== ====== ======== ==========

URI                      Method Cyclades OS/Compute

======================== ====== ======== ==========

``/servers/<server id>`` PUT    ✔        ✔

======================== ====== ======== ==========

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

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

Content-Type    Type or request body      required required

Content-Length  Length of request body    required required

==============  ========================= ======== ==========

**Example Request Headers**::

  X-Auth-Token:   z31uRXUn1LZy45p1r7V==

  Content-Type:   application/json

  Content-Length: 54

.. note:: Request parameters should be empty

Request body contents::

  server: {

    <server attribute>: <value>,

    ...

  }

=========== ==================== ======== ==========

Attribute   Description          Cyclades OS/Compute

=========== ==================== ======== ==========

name        The server name      ✔        ✔

accessIPv4  IP v4 address        **✘**    ✔

accessIPv6  IP v6 address        **✘**    ✔

=========== ==================== ======== ==========

* Cyclades support multiple network connections per virtual server, which

  explains the above differences in request body attributes.

*Example Rename Server Request: JSON*

.. code-block:: javascript

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

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

204 (OK)                    Request succeeded

400 (Bad Request)           Malformed request or malformed server id

401 (Unauthorized)          Missing or expired user token

403 (Forbidden)             User is not allowed to perform this operation

404 (Not Found)             Server not found

415 (Bad Media Type)

409 (Build In Progress)     Server is not ready yet

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   No available backends or service currently

\                           unavailable

=========================== =====================

.. note:: In case of a 204 return code, there will be no request results

  according to the Cyclades API. Compute OS API suggests that response should

  include the new server details.

Delete Server

.............

Delete a virtual server. When a server is deleted, all its connections are

deleted as well.

.. rubric:: Request

======================== ====== ======== ==========

URI                      Method Cyclades OS/Compute

======================== ====== ======== ==========

``/servers/<server id>`` DELETE ✔        ✔

======================== ====== ======== ==========

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

|

==============  ========================= ======== ==========

Request Header  Value                     Cyclades OS/Compute

==============  ========================= ======== ==========

X-Auth-Token    User authentication token required required

==============  ========================= ======== ==========

.. note:: Request parameters should be empty

.. note:: Request body should be empty

.. rubric:: Response

=========================== =====================

Return Code                 Description

=========================== =====================

204 (OK)                    Request succeeded

400 (Bad Request)           Malformed server id or machine already deleted

401 (Unauthorized)          Missing or expired user token

404 (Not Found)             Server not found

409 (Build In Progress)     Server is not ready yet

500 (Internal Server Error) The request cannot be completed because of an

\                           internal error

503 (Service Unavailable)   Action not supported or service currently

\                           unavailable

=========================== =====================

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

List Server Addresses