API Guide¶

This is the guide to the REST API of the synnefo Compute Service. It is meant for users wishing to make calls to the REST API directly.

The kamaki command-line client and associated python library can be used instead of making direct calls to cyclades.

Overview¶

It is not defined if requests for invalid URLs should return 404 or a Fault. We return a BadRequest Fault.
It is not defined if requests with a wrong HTTP method should return 405 or a Fault. We return a BadRequest Fault.

General API Information¶

Authentication¶

Authentication support is missing.

Request/Response Types¶

We only support JSON Requests and JSON/XML Responses. XML Requests are not supported for now.

Content Compression¶

Optional content compression support is missing.

Persistent Connections¶

Deployment note: “To prevent abuse, HTTP sessions have a timeout of 20 seconds before being closed.”

Links and References¶

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

Paginated Collections¶

Pagination support is missing.

Caching¶

We do not return cached responses.

Limits¶

Limits support is missing.

Efficient Polling with the Changes-Since Parameter¶

We only support the changes-since parameter in List Servers and List Images.
We assume that garbage collection of deleted servers will only affect servers deleted POLL_TIME seconds in the past or earlier. Else we lose the information of a server getting deleted.
Images do not support a deleted state, so we can not track deletions.

Versions¶

Version MIME type support is missing.
Versionless requests are not supported.
We hardcode the updated field in versions list
Deployment note: The Atom metadata need to be fixed

Extensions¶

Extensions support is missing.

Faults¶

API Operations¶

Servers¶

hostId is always empty.
affinityId is not returned.
progress is always returned.
self and bookmark atom links are not returned.
Get Server Details will also return servers with a DELETED state.
Create Server does not support setting the password in the request.

List Servers¶

List Servers returns just id and name if details are not requested.
List Servers can return 304 (even though not explicitly stated) when changes-since is given.

Example List Servers: JSON

{
    'servers':
        {'values': [
            {
                'addresses': {'values': [
                        {
                            'id': 'public',
                            'mac': 'aa:00:00:49:2e:7e',
                            'name': 'public',
                            'values': [ {'addr': '192.168.32.6', 'version': 4} ]
                        }
                ]},
                'created': '2011-04-19T10:18:52.085737+00:00',
                'flavorRef': 1,
                'hostId': '',
                'id': 1,
                'imageRef': 3,
                'metadata': {'values': {'foo': 'bar'}},
                'name': 'My Server',
                'status': 'ACTIVE',
                'updated': u'2011-05-29T14:07:07.037602+00:00'
            },
            {
                'addresses': {'values': [
                        {
                            'id': 'public',
                            'mac': 'aa:00:00:91:2f:df',
                            'name': 'public',
                            'values': [ {'addr': '192.168.32.7', 'version': 4} ]
                        },
                        {
                            'id': '2',
                            'mac': 'aa:00:00:c3:69:6f',
                            'name': 'private'
                        },
                ]},
                'created': '2011-05-02T20:51:08.527759+00:00',
                'flavorRef': 1,
                'hostId': '',
                'id': 2,
                'imageRef': 3,
                'name': 'Other Server',
                'progress': 0,
                'status': 'ACTIVE',
                'updated': '2011-05-29T14:59:11.267087+00:00'
            }
        ]
    }
}

Get Server Stats¶

GET /servers/id/stats

Normal Response Code: 200

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

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

This operation does not require a request body.

Example Get Server Stats Response: JSON:

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

Example Get Network Details Response: 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="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png"
    cpuTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png"
    netBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png"
    netTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png">
</stats>

Server Addresses¶

Server Actions¶

Change Password is not supported.
Rebuild Server is not supported.
Resize Server is not supported.
Confirm Resized Server is not supported.
Revert Resized Server is not supported.

We have have extended the API with the following commands:

Start Server¶

Normal Response Code: 202

Error Response Codes: serviceUnavailable (503), itemNotFound (404)

The start function transitions a server from an ACTIVE to a STOPPED state.

Example Action Start: JSON:

{
    "start": {}
}

This operation does not return a response body.

Shutdown Server¶

Normal Response Code: 202

Error Response Codes: serviceUnavailable (503), itemNotFound (404)

The start function transitions a server from a STOPPED to an ACTIVE state.

Example Action Shutdown: JSON:

{
    "shutdown": {}
}

This operation does not return a response body.

Get Server Console

Normal Response Code: 200

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), buildInProgress (409), overLimit (413)

The console function arranges for an OOB console of the specified type. Only consoles of type “vnc” are supported for now.

It uses a running instance of vncauthproxy to setup proper VNC forwarding with a random password, then returns the necessary VNC connection info to the caller.

Example Action Console: JSON:

{
    "console": {
        "type": "vnc"
    }
}

Example Action Console Response: JSON:

{
    "console": {
        "type": "vnc",
        "host": "vm42.ocean.grnet.gr",
        "port": 1234,
        "password": "IN9RNmaV"
    }
}

Example Action Console Response: XML:

<?xml version="1.0" encoding="UTF-8"?>
<console xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"
    type="vnc"
    host="vm42.ocean.grnet.gr"
    port="1234"
    password="IN9RNmaV">
</console>

Set Firewall Profile¶

Normal Response Code: 202

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), buildInProgress (409), overLimit (413)

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

The allowed profiles are: ENABLED, DISABLED and PROTECTED.

Example Action firewallProfile: JSON:

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

This operation does not return a response body.

Flavors¶

self and bookmark atom links are not returned.
List Flavors returns just id and name if details is not requested.

Images¶

progress is always returned.
self and bookmark atom links are not returned.
List Images returns just id and name if details are not requested.
List Images can return 304 (even though not explicitly stated) when changes-since is given.
List Images does not return deleted images when changes-since is given.

Metadata¶

Update Server Metadata and Update Image Metadata will only return the metadata that were updated (some could have been skipped).

Networks¶

This is an extension to the OpenStack API.

A Server can connect to one or more networks identified by a numeric id. Each user has access only to networks created by himself. When a network is deleted, all connections to it are deleted. Likewise, when a server is deleted, all connections of that server are deleted.

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

List Networks¶

GET /networks

GET /networks/detail

Normal Response Codes: 200, 203

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

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

This operation does not require a request body.

Example Networks List Response: JSON (detail):

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

Example Networks List Response: XML (detail):

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

Create Network¶

POST /networks

Normal Response Code: 202

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badMediaType(415), badRequest (400), overLimit (413)

This operation asynchronously provisions a new private network.

Example Create Network Request: JSON:

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

Example Create Network Response: JSON:

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

Example Create Network Response: XML:

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

Get Network Details¶

GET /networks/id

Normal Response Codes: 200, 203

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

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

This operation does not require a request body.

Example Get Network Details Response: JSON:

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

Example Get Network Details Response: XML:

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

Update Network Name¶

PUT /networks/id

Normal Response Code: 204

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), overLimit (413)

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

Example Update Network Name Request: JSON:

{
    "network": {
        "name": "new_name"
    }
}

This operation does not contain a response body.

Delete Network¶

DELETE /networks/id

Normal Response Code: 204

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), itemNotFound (404), unauthorized (401), overLimit (413)

This operation deletes a network from the system.

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

Network Actions¶

Add Server¶

POST /networks/id/action

Normal Response Code: 202

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), overLimit (413)

This operation adds a server to the specified network.

Example Action Add: JSON:

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

This operation does not contain a response body.

Remove Server¶

POST /networks/id/action

Normal Response Code: 202

Error Response Codes: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), overLimit (413)

This operation removes a server from the specified network.

Example Action Remove: JSON:

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

This operation does not contain a response body.

API Guide¶

Overview¶

General API Information¶

Authentication¶

Request/Response Types¶

Content Compression¶

Persistent Connections¶

Links and References¶

Paginated Collections¶

Caching¶

Limits¶

Efficient Polling with the Changes-Since Parameter¶

Versions¶

Extensions¶

Faults¶

API Operations¶

Servers¶

List Servers¶

Get Server Stats¶

Server Addresses¶

Server Actions¶

Start Server¶

Shutdown Server¶

Set Firewall Profile¶

Flavors¶

Images¶

Metadata¶

Networks¶

List Networks¶

Create Network¶

Get Network Details¶

Update Network Name¶

Delete Network¶

Network Actions¶

Add Server¶

Remove Server¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

API Guide¶

Overview¶

General API Information¶

Authentication¶

Request/Response Types¶

Content Compression¶

Persistent Connections¶

Links and References¶

Paginated Collections¶

Caching¶

Limits¶

Efficient Polling with the Changes-Since Parameter¶

Versions¶

Extensions¶

Faults¶

API Operations¶

Servers¶

List Servers¶

Get Server Stats¶

Server Addresses¶

Server Actions¶

Start Server¶

Shutdown Server¶

Set Firewall Profile¶

Flavors¶

Images¶

Metadata¶

Networks¶

List Networks¶

Create Network¶

Get Network Details¶

Update Network Name¶

Delete Network¶

Network Actions¶

Add Server¶

Remove Server¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation