Skip to content

GitLab

Commit c93fb732 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Merge branch 'feature-apidocs-0.15' into release-0.15

parents 3b7d3e38 0c47e02c
Hide whitespace changes
Inline Side-by-side
Showing with 2251 additions and 1663 deletions
docs/api-guide.rst
View file @ c93fb732
......@@ -15,12 +15,13 @@ for things that were missing or change frequently.
Most Synnefo services have a corresponding OpenStack API:
| Cyclades/Compute Service -> OpenStack Compute API
| Cyclades/Network Service -> OpenStack Neutron API
| Cyclades/Image Service -> OpenStack Glance API
| Pithos/Storage Service -> OpenStack Object Store API
| Astakos/Identity Service -> OpenStack Keystone API
| Cyclades/Network Service -> OpenStack Networking ("Neutron") API
| Cyclades/Image Service -> OpenStack Image ("Glance") API
| Pithos/Storage Service -> OpenStack Object Storage API
| Astakos/Identity Service -> OpenStack Identity ("Keystone") API
| Astakos/Quota Service -> Proprietary API
| Astakos/Resource Service -> Proprietary API
| Astakos/Project Service -> Proprietary API
Below, we will describe all Synnefo APIs with conjuction to the OpenStack APIs.
......@@ -29,7 +30,7 @@ Identity Service API (Astakos)
==============================
The Identity Management Service of Synnefo, which is part of Astakos, exposes
the OpenStack Keystone API.
the OpenStack Identity ("Keystone") API.
The current Astakos/Identity API is:
......@@ -80,7 +81,7 @@ Network Service API (Cyclades)
==============================
The Network Service is implemented inside Cyclades. It exposes the OpenStack
Neutron API.
Networking ("Neutron") API.
This is the Cyclades/Network API:
......@@ -94,7 +95,7 @@ Image Service API (Cyclades)
============================
The Image Service is implemented inside Cyclades. It exposes the OpenStack
Glance API with minor changes wherever needed.
Image ("Glance") API with minor changes wherever needed.
This is the Cyclades/Image API:
......@@ -147,15 +148,15 @@ which can be represented as folders or with other related icons:
organization of folders and files.
* The ``trash`` element, which contains files that have been marked for
deletion, but can still be recovered.
* The ``shared`` element, which contains all objects shared by the user to
other users of the system.
* The ``others`` element, which contains all objects that other users share
with the user.
* The ``shared by me`` element, which contains all objects shared by the
user to other users of the system.
* The ``shared with me`` element, which contains all objects that other users
share with the user.
* The ``groups`` element, which contains the names of groups the user has
defined. Each group consists of a user list. Group creation, deletion, and
manipulation is carried out by actions originating here.
* The ``history`` element, which allows browsing past instances of ``home``
and - optionally - ``trash``.
.. * The ``history`` element, which allows browsing past instances of ``home``
.. and - optionally - ``trash``.
Objects in Pithos can be:
......
docs/compute-api-guide.rst
View file @ c93fb732
......@@ -4,9 +4,9 @@ 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.
<http://www.synnefo.org>`_. The Cyclades/Compute API complies with
`OpenStack Compute <http://docs.openstack.org/api/openstack-compute/2/content>`_
with custom extensions when needed.
This document's goals are:
......@@ -14,7 +14,8 @@ This document's goals are:
* 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://www.synnefo.org/docs/kamaki/latest/index.html>`_ command-line
advised to use the
`kamaki <http://www.synnefo.org/docs/kamaki/latest/index.html>`_ command-line
client and associated python library, instead of making direct calls.
Overview
......@@ -74,32 +75,59 @@ Limitations
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>/metadata`` GET ✔ ✔
`Update Metadata <#set-update-server-metadata>`_ ``/servers/<server-id>/metadata`` PUT **✘** ✔
\ ``/servers/<server-id>/metadata`` POST ✔ ✔
`Get Meta Item <#get-server-metadata-item>`_ ``/servers/<server-id>/metadata/<key>`` GET ✔ ✔
`Update Meta Item <#update-server-metadatum-item>`_ ``/servers/<server-id>/metadata/<key>`` PUT ✔ ✔
`Delete Meta Item <#delete-server-metadatum>`_ ``/servers/<server-id>/metadata/<key>`` DELETE ✔ ✔
=================================================== ========================================= ====== ======== ==========
.. rubric:: 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 Connections <#list-server-connections>`_ ``/servers/<server id>/ips`` GET ✔ ✔
`Get Connection <#connection-with-network>`_ ``/servers/<server id>/ips/<network id>`` GET ✔ ✔
`List Metadata <#list-server-metadata>`_ ``/servers/<server-id>/metadata`` GET ✔ ✔
`Update Metadata <#set-update-server-metadata>`_ ``/servers/<server-id>/metadata`` PUT **✘** ✔
\ ``/servers/<server-id>/metadata`` POST ✔ ✔
`Get Meta Item <#get-server-metadata-item>`_ ``/servers/<server-id>/metadata/<key>`` GET ✔ ✔
`Update Meta Item <#update-server-metadata-item>`_ ``/servers/<server-id>/metadata/<key>`` PUT ✔ ✔
`Delete Meta Item <#delete-server-metadata>`_ ``/servers/<server-id>/metadata/<key>`` DELETE ✔ ✔
`Actions <#server-actions>`_ ``servers/<server id>/action`` POST ✔ ✔
================================================== ========================================= ====== ======== ==========
.. rubric:: Flavors
==================================== ======================== ====== ======== ==========
Description URI Method Cyclades OS/Compute
==================================== ======================== ====== ======== ==========
`List <#list-flavors>`_ ``/flavors`` GET ✔ ✔
\ ``/flavors/detail`` GET ✔ **✘**
`Get details <#get-flavor-details>`_ ``/flavors/<flavor-id>`` GET ✔ ✔
==================================== ======================== ====== ======== ==========
.. rubric:: Images
=========================================== ===================================== ====== ======== ==========
Description URI Method Cyclades OS/Compute
=========================================== ===================================== ====== ======== ==========
`List <#list-images>`_ ``/images`` GET ✔ ✔
\ ``/images/detail`` GET ✔ ✔
`Get details <#get-image-details>`_ ``/images/<image-id>`` GET ✔ ✔
`Delete <#delete-image>`_ ``/images/<image id>`` DELETE ✔ ✔
`List Metadata <#list-image-metadata>`_ ``/images/<image-id>/metadata`` GET ✔ ✔
`Update Metadata <#update-image-metadata>`_ ``/images/<image-id>/metadata`` POST ✔ ✔
\ ``/images/<image-id>/metadata`` PUT **✘** ✔
`Get Meta Item <#get-image-metadata>`_ ``/image/<image-id>/metadata/<key>`` GET ✔ ✔
`Update Metadata <#update-image-metadata>`_ ``/images/<image-id>/metadata/<key>`` PUT ✔ ✔
`Delete Metadata <#delete-image-metadata>`_ ``/images/<image-id>/metadata/<key>`` DELETE ✔ ✔
=========================================== ===================================== ====== ======== ==========
List Servers
............
------------
List all virtual servers owned by the user.
......@@ -117,7 +145,6 @@ URI Method Cyclades OS/Compute
server attributes.
|
============== ========================= ======== ==========
Request Header Value Cyclades OS/Compute
============== ========================= ======== ==========
......@@ -125,7 +152,6 @@ X-Auth-Token User authentication token required required
============== ========================= ======== ==========
|
================= =================================== ======== ==========
Request Parameter Value Cyclades OS/Compute
================= =================================== ======== ==========
......@@ -147,8 +173,6 @@ the response will be formated in json.
* **changes-since** must be an ISO8601 date string
.. note:: Request body should be empty
.. rubric:: Response
=========================== =====================
......@@ -175,225 +199,272 @@ Response body contents::
}, ...
]
================= ====================== ======== ==========
Server Attributes Description Cyclades OS/Compute
================= ====================== ======== ==========
id The server id ✔ ✔
name The server name ✔ ✔
links Reference links ✔ ✔
hostId Server playground empty ✔
created Creation date ✔ ✔
updated Creation date ✔ ✔
flavor The flavor 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>`_.
The server attributes are listed `here <#server-ref>`_
*Example List Servers: JSON (regular)*
.. code-block:: javascript
[
GET https://example.org/compute/v2.0/servers
{
"servers": [
{
"links": [
{
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "bookmark"
}
{
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "bookmark"
}
],
"id": "42",
"name": "My Server",
}, {
"links": [
{
"href": "https://example.org/compute/v2.0/servers/43",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/servers/43",
"rel": "bookmark"
}
{
"href": "https://example.org/compute/v2.0/servers/43",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/servers/43",
"rel": "bookmark"
}
],
"id": "43",
"id": "84",
"name": "My Server",
}
]
}
*Example List Servers: JSON (detail)*
GET https://example.org/compute/v2.0/servers/detail
.. code-block:: javascript
[
{
"servers": [
{
"addresses": [
"2718": [
{
"version": 6,
"addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab",
"OS-EXT-IPS:type": "fixed"
}
],
"2719": [
{
"version": 4,
"addr": "192.168.1.2",
"OS-EXT-IPS:type": "floating"
}
]
],
"attachments": [
{
"id": "nic-42-0",
"network_id": "101",
"mac_address": "aa:00:00:49:2e:7e",
"id": "18",
"network_id": "2718",
"mac_address": "aa:01:02:6c:34:ab",
"firewallProfile": "DISABLED",
"ipv4": "192.168.4.5",
"ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5b"
"ipv4": "",
"ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab"
"OS-EXT-IPS:type": "fixed"
}, {
"id": "19",
"network_id": "2719",
"mac_address": "aa:00:0c:6d:34:bb",
"firewallProfile": "PROTECTED",
"ipv4": "192.168.1.2",
"ipv6": ""
"OS-EXT-IPS:type": "floating"
}
],
"links": [
{
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "bookmark"
}
],
"image": {
"id": "im4g3-1d",
"links": [
{
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/servers/42",
"rel": "bookmark"
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "bookmark"
}, {
"href": "https://example.org/image/v1.0/images/im4g3-1d",
"rel": "alternate"
}
],
]
},
"suspended": false,
"created': '2011-04-19T10:18:52.085737+00:00',
"flavor": {
"id": 1",
"links": [
{
"href": "https://example.org/compute/v2.0/flavors/1",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/flavors/1",
"rel": "bookmark"
}
]
"id": 1",
"links": [
{
"href": "https://example.org/compute/v2.0/flavors/1",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/flavors/1",
"rel": "bookmark"
}
]
},
"hostId": "",
"id": "42",
"image": {
"id": "im4g3-1d",
"links": [
{
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "bookmark"
},
{
"href": "https://example.org/image/v1.0/images/im4g3-1d",
"rel": "alternate"
}
]
},
"metadata": {{"foo": "bar"},
"name": "My Server",
"security_groups": [{"name": "default"}],
"user_id": "s0m5-u5e7-1d",
"accessIPv4": "",
"accessIPv6": "",
"progress": 100,
"config_drive": "",
"status": "ACTIVE",
"updated": "2011-05-29T14:07:07.037602+00:00"
"updated": "2011-05-29T14:07:07.037602+00:00",
"hostId": "",
"SNF:fqdn": "snf-42.vm.example.org",
"key_name": null,
"name": "My Server",
"created": "2014-02-12T08:31:37.834542+00:00",
"tenant_id": "s0m5-u5e7-1d",
"SNF:port_forwarding": {},
"SNF:task_state": "",
"diagnostics": [
{
"level": "DEBUG",
"created": "2014-02-12T08:31:37.834542+00:00",
"source": "image-info",
"source_date": "2014-02-12T08:32:35.929507+00:00",
"message": "Image customization finished successfully.",
"details": null
}
],
"metadata": {
"os": "debian",
"users": "root"
}
}, {
{
"addresses": [
"2718": [
{
"version": 6,
"addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd",
"OS-EXT-IPS:type": "fixed"
}
],
"4178": [
{
"version": 4,
"addr": "192.168.1.3",
"OS-EXT-IPS:type": "floating"
}
]
],
"attachments": [
{
"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",
"id": "36",
"network_id": "2718",
"mac_address": "aa:01:02:6c:34:cd",
"firewallProfile": "DISABLED",
"ipv4": "192.168.32.6",
"ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5c'
"ipv4": "",
"ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd"
"OS-EXT-IPS:type": "fixed"
}, {
"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"
"id": "38",
"network_id": "4178",
"mac_address": "aa:00:0c:6d:34:cc",
"firewallProfile": "PROTECTED",
"ipv4": "192.168.1.3",
"ipv6": ""
"OS-EXT-IPS:type": "floating"
}
],
"links": [
{
"href": "https://example.org/compute/v2.0/servers/84",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/servers/84",
"rel": "bookmark"
}
],
"image": {
"id": "im4g3-1d",
"links": [
{
"href": "https://example.org/compute/v2.0/servers/43",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/servers/43",
"rel": "bookmark"
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "bookmark"
}, {
"href": "https://example.org/image/v1.0/images/im4g3-1d",
"rel": "alternate"
}
],
"created": "2011-05-02T20:51:08.527759+00:00",
"flavor": {
"id": 1",
"links": [
{
"href": "https://example.org/compute/v2.0/flavors/1",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/flavors/1",
"rel": "bookmark"
}
]
]
},
"hostId": "",
"id": "43",
"image": {
"id": "im4g3-1d",
"links": [
{
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "bookmark"
},
{
"href": "https://example.org/image/v1.0/images/im4g3-1d",
"rel": "alternate"
}
]
"suspended": false,
"created': '2011-04-21T10:18:52.085737+00:00',
"flavor": {
"id": 3",
"links": [
{
"href": "https://example.org/compute/v2.0/flavors/3",
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/flavors/3",
"rel": "bookmark"
}
]
},
"name": "Other Server",
"description": "A sample server to showcase server requests",
"progress": "0",
"id": "84",
"security_groups": [{"name": "default"}],
"user_id": "s0m5-u5e7-1d",
"accessIPv4": "",
"accessIPv6": "",
"progress": 100,
"config_drive": "",
"status": "ACTIVE",
"updated": "2011-05-29T14:59:11.267087+00:00"
"updated": "2011-05-30T14:07:07.037602+00:00",
"hostId": "",
"SNF:fqdn": "snf-84.vm.example.org",
"key_name": null,
"name": "My Other Server",
"created": "2014-02-21T08:31:37.834542+00:00",
"tenant_id": "s0m5-u5e7-1d",
"SNF:port_forwarding": {},
"SNF:task_state": "",
"diagnostics": [
{
"level": "DEBUG",
"created": "2014-02-21T08:31:37.834542+00:00",
"source": "image-info",
"source_date": "2014-02-21T08:32:35.929507+00:00",
"message": "Image customization finished successfully.",
"details": null
}
],
"metadata": {
"os": "debian",
"users": "root"
}
}
]
}
Create Server
.............
-------------
Create a new virtual server
......@@ -406,7 +477,6 @@ URI Method Cyclades OS/Compute
============ ====== ======== ==========
|
============== ========================= ======== ==========
Request Header Value Cyclades OS/Compute
============== ========================= ======== ==========
......@@ -415,14 +485,7 @@ 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
================= ===============
......@@ -436,24 +499,25 @@ Request body contents::