Revision 3458183d
| b/docs/cyclades-api-guide.rst | ||
|---|---|---|
| 3 | 3 |
API Guide |
| 4 | 4 |
********* |
| 5 | 5 |
|
| 6 |
`Cyclades <cyclades.html>`_ is the compute service developed by `GRNET
|
|
| 7 |
<http://www.grnet.gr>`_ as part of the `synnefo <http://www.synnefo.org>`_
|
|
| 8 |
software. Cyclades API started as an extension of the `OpenStack Compute API v2
|
|
| 9 |
<http://docs.openstack.org/api/openstack-compute/2/content>`_. |
|
| 6 |
`Cyclades <cyclades.html>`_ is the Compute Service of `Synnefo
|
|
| 7 |
<http://www.synnefo.org>`_. The Cyclades API tries to be as close to the
|
|
| 8 |
`OpenStack Compute API v2 |
|
| 9 |
<http://docs.openstack.org/api/openstack-compute/2/content>`_ as possible.
|
|
| 10 | 10 |
|
| 11 | 11 |
This document's goals are: |
| 12 | 12 |
|
| 13 |
* Define the Cyclades/Compute ReST API
|
|
| 14 |
* Clarify the differences between Cyclades and OS/Compute
|
|
| 13 |
* Define the Cyclades/Compute REST API
|
|
| 14 |
* Clarify the differences between Cyclades and OpenStack/Compute
|
|
| 15 | 15 |
|
| 16 |
Users and developers who wish to access a Synnefo Cyclades deployment through |
|
| 17 |
its ReST API are advised to use the `kamaki <http://docs.dev.grnet.gr/kamaki>`_ |
|
| 18 |
command-line client and associated python library, instead of making direct |
|
| 19 |
calls. |
|
| 16 |
Users and developers who wish to access Cyclades through its REST API are |
|
| 17 |
advised to use the `kamaki <http://docs.dev.grnet.gr/kamaki>`_ command-line |
|
| 18 |
client and associated python library, instead of making direct calls. |
|
| 20 | 19 |
|
| 21 | 20 |
Overview |
| 22 | 21 |
======== |
| 23 | 22 |
|
| 24 |
* It is not defined if requests for invalid URLs should return 404 or a Fault.
|
|
| 25 |
We return a BadRequest Fault.
|
|
| 26 |
* It is not defined if requests with a wrong HTTP method should return 405 or a
|
|
| 27 |
Fault. We return a BadRequest Fault.
|
|
| 23 |
* OpenStack does not define if requests for invalid URLs should return 404 or a
|
|
| 24 |
* Fault. We return a BadRequest Fault.
|
|
| 25 |
* OpenStack does not define if requests with a wrong HTTP method should return
|
|
| 26 |
* 405 or a Fault. We return a BadRequest Fault.
|
|
| 28 | 27 |
|
| 29 | 28 |
General API Information |
| 30 | 29 |
======================= |
| ... | ... | |
| 326 | 325 |
| |
| 327 | 326 |
|
| 328 | 327 |
================= =============== |
| 329 |
Request Parameter Value
|
|
| 328 |
Request Parameter Value |
|
| 330 | 329 |
================= =============== |
| 331 | 330 |
json Respond in json |
| 332 |
xml Respond in xml
|
|
| 331 |
xml Respond in xml |
|
| 333 | 332 |
================= =============== |
| 334 | 333 |
|
| 335 | 334 |
Request body contents:: |
| ... | ... | |
| 425 | 424 |
403 (Forbidden) User is not allowed to perform this operation |
| 426 | 425 |
404 (Not Found) Image or Flavor not found |
| 427 | 426 |
413 (Over Limit) Exceeded some resource limit (#VMs, personality |
| 428 |
size, etc.)
|
|
| 427 |
size, etc.) |
|
| 429 | 428 |
415 (Bad Media Type) |
| 430 | 429 |
500 (Internal Server Error) The request cannot be completed because of an |
| 431 | 430 |
\ internal error |
| ... | ... | |
| 550 | 549 |
stats: {<parameter>: <value> }
|
| 551 | 550 |
|
| 552 | 551 |
============= ====================== |
| 553 |
Parameter Description
|
|
| 552 |
Parameter Description |
|
| 554 | 553 |
============= ====================== |
| 555 | 554 |
serverRef Server ID |
| 556 | 555 |
refresh Refresh frequency |
| ... | ... | |
| 657 | 656 |
level Debug level |
| 658 | 657 |
created Log entry timestamp |
| 659 | 658 |
source Log source proccess |
| 660 |
source_date Log source date
|
|
| 659 |
source_date Log source date |
|
| 661 | 660 |
message Log description |
| 662 | 661 |
details Detailed log description |
| 663 | 662 |
==================== =========== |
| ... | ... | |
| 1099 | 1098 |
... |
| 1100 | 1099 |
} |
| 1101 | 1100 |
|
| 1102 |
Network Interface Connection (NIC) attributes are listed `here <#nic-ref>`_.
|
|
| 1101 |
Network Interface Connection (NIC) attributes are listed `here <#nic-ref>`_. |
|
| 1103 | 1102 |
|
| 1104 | 1103 |
**List Server NICs Example with server id 25455, network id 7: JSON** |
| 1105 | 1104 |
|
| ... | ... | |
| 1176 | 1175 |
|
| 1177 | 1176 |
.. code-block:: javascript |
| 1178 | 1177 |
|
| 1179 |
{
|
|
| 1178 |
{
|
|
| 1180 | 1179 |
""metadata": {
|
| 1181 | 1180 |
"values": {
|
| 1182 | 1181 |
"OS": "Linux", |
| ... | ... | |
| 1565 | 1564 |
*Example (soft) Reboot Server: JSON* |
| 1566 | 1565 |
|
| 1567 | 1566 |
.. code-block:: javascript |
| 1568 |
|
|
| 1567 |
|
|
| 1569 | 1568 |
{"reboot" : { "type": "soft"}}
|
| 1570 | 1569 |
|
| 1571 | 1570 |
.. note:: Response body should be empty |
| ... | ... | |
| 1615 | 1614 |
} |
| 1616 | 1615 |
|
| 1617 | 1616 |
============== ====================== |
| 1618 |
VNC Attributes Description
|
|
| 1617 |
VNC Attributes Description |
|
| 1619 | 1618 |
============== ====================== |
| 1620 | 1619 |
host The vncprocy host |
| 1621 | 1620 |
port vncprocy port |
| ... | ... | |
| 1712 | 1711 |
| |
| 1713 | 1712 |
|
| 1714 | 1713 |
================= =============== |
| 1715 |
Request Parameter Value
|
|
| 1714 |
Request Parameter Value |
|
| 1716 | 1715 |
================= =============== |
| 1717 | 1716 |
json Respond in json |
| 1718 |
xml Respond in xml
|
|
| 1717 |
xml Respond in xml |
|
| 1719 | 1718 |
================= =============== |
| 1720 | 1719 |
|
| 1721 | 1720 |
.. note:: Request body should be empty |
| ... | ... | |
| 1831 | 1830 |
| |
| 1832 | 1831 |
|
| 1833 | 1832 |
================= =============== |
| 1834 |
Request Parameter Value
|
|
| 1833 |
Request Parameter Value |
|
| 1835 | 1834 |
================= =============== |
| 1836 | 1835 |
json Respond in json |
| 1837 |
xml Respond in xml
|
|
| 1836 |
xml Respond in xml |
|
| 1838 | 1837 |
================= =============== |
| 1839 | 1838 |
|
| 1840 | 1839 |
.. note:: Request body should be empty |
| ... | ... | |
| 1866 | 1865 |
*Example Flavor Details: JSON* |
| 1867 | 1866 |
|
| 1868 | 1867 |
.. code-block:: javascript |
| 1869 |
|
|
| 1868 |
|
|
| 1870 | 1869 |
{
|
| 1871 | 1870 |
"flavor": {
|
| 1872 | 1871 |
{
|
| ... | ... | |
| 2229 | 2228 |
|
| 2230 | 2229 |
.. code-block:: javascript |
| 2231 | 2230 |
|
| 2232 |
{
|
|
| 2231 |
{
|
|
| 2233 | 2232 |
"metadata": {
|
| 2234 | 2233 |
"values": {
|
| 2235 | 2234 |
"partition_table": "msdos", |
| ... | ... | |
| 2331 | 2330 |
|
| 2332 | 2331 |
.. code-block:: javascript |
| 2333 | 2332 |
|
| 2334 |
{
|
|
| 2333 |
{
|
|
| 2335 | 2334 |
"metadata": {
|
| 2336 | 2335 |
"partition_table": "msdos", |
| 2337 | 2336 |
"kernel": "3.2.0", |
| ... | ... | |
| 2582 | 2581 |
| |
| 2583 | 2582 |
|
| 2584 | 2583 |
============== ========================= |
| 2585 |
Request Header Value
|
|
| 2584 |
Request Header Value |
|
| 2586 | 2585 |
============== ========================= |
| 2587 | 2586 |
X-Auth-Token User authentication token |
| 2588 | 2587 |
============== ========================= |
| ... | ... | |
| 2597 | 2596 |
Return Code Description |
| 2598 | 2597 |
=========================== ===================== |
| 2599 | 2598 |
204 (OK) Request succeeded |
| 2600 |
304 (Not Modified)
|
|
| 2599 |
304 (Not Modified) |
|
| 2601 | 2600 |
400 (Bad Request) Malformed network id |
| 2602 | 2601 |
401 (Unauthorized) Missing or expired user token |
| 2603 | 2602 |
404 (Not Found) Network not found |
| ... | ... | |
| 2677 | 2676 |
| |
| 2678 | 2677 |
|
| 2679 | 2678 |
============== ========================= |
| 2680 |
Request Header Value
|
|
| 2679 |
Request Header Value |
|
| 2681 | 2680 |
============== ========================= |
| 2682 | 2681 |
X-Auth-Token User authentication token |
| 2683 | 2682 |
Content-Type Type or request body |
| ... | ... | |
| 2702 | 2701 |
================== ======================= ======== ======= |
| 2703 | 2702 |
Request Attributes Description Required Default |
| 2704 | 2703 |
================== ======================= ======== ======= |
| 2705 |
name Network name ✔
|
|
| 2704 |
name Network name ✔ |
|
| 2706 | 2705 |
type Network type ✔ |
| 2707 | 2706 |
dhcp If use DHCP **✘** True |
| 2708 | 2707 |
cidr IPv4 CIDR **✘** 192.168.1.0/2 |
| ... | ... | |
| 2786 | 2785 |
========================== ====== |
| 2787 | 2786 |
URI Method |
| 2788 | 2787 |
========================== ====== |
| 2789 |
``/networks/<network-id>`` GET
|
|
| 2788 |
``/networks/<network-id>`` GET |
|
| 2790 | 2789 |
========================== ====== |
| 2791 | 2790 |
|
| 2792 | 2791 |
* **network-id** is the identifier of the network |
| ... | ... | |
| 2794 | 2793 |
| |
| 2795 | 2794 |
|
| 2796 | 2795 |
============== ========================= |
| 2797 |
Request Header Value
|
|
| 2796 |
Request Header Value |
|
| 2798 | 2797 |
============== ========================= |
| 2799 | 2798 |
X-Auth-Token User authentication token |
| 2800 | 2799 |
============== ========================= |
| ... | ... | |
| 2856 | 2855 |
========================== ====== |
| 2857 | 2856 |
URI Method |
| 2858 | 2857 |
========================== ====== |
| 2859 |
``/networks/<network-id>`` PUT
|
|
| 2858 |
``/networks/<network-id>`` PUT |
|
| 2860 | 2859 |
========================== ====== |
| 2861 | 2860 |
|
| 2862 | 2861 |
* **network-id** is the identifier of the network |
| ... | ... | |
| 2864 | 2863 |
| |
| 2865 | 2864 |
|
| 2866 | 2865 |
============== ========================= |
| 2867 |
Request Header Value
|
|
| 2866 |
Request Header Value |
|
| 2868 | 2867 |
============== ========================= |
| 2869 | 2868 |
X-Auth-Token User authentication token |
| 2870 |
Content-Type Type or request body
|
|
| 2871 |
Content-Length Length of request body
|
|
| 2869 |
Content-Type Type or request body |
|
| 2870 |
Content-Length Length of request body |
|
| 2872 | 2871 |
============== ========================= |
| 2873 | 2872 |
|
| 2874 | 2873 |
**Example Request Headers**:: |
| ... | ... | |
| 2918 | 2917 |
========================== ====== |
| 2919 | 2918 |
URI Method |
| 2920 | 2919 |
========================== ====== |
| 2921 |
``/networks/<network-id>`` DELETE
|
|
| 2920 |
``/networks/<network-id>`` DELETE |
|
| 2922 | 2921 |
========================== ====== |
| 2923 | 2922 |
|
| 2924 | 2923 |
* **network-id** is the identifier of the network |
| ... | ... | |
| 2926 | 2925 |
| |
| 2927 | 2926 |
|
| 2928 | 2927 |
============== ========================= |
| 2929 |
Request Header Value
|
|
| 2928 |
Request Header Value |
|
| 2930 | 2929 |
============== ========================= |
| 2931 | 2930 |
X-Auth-Token User authentication token |
| 2932 | 2931 |
============== ========================= |
| ... | ... | |
| 2973 | 2972 |
| |
| 2974 | 2973 |
|
| 2975 | 2974 |
============== ========================= |
| 2976 |
Request Header Value
|
|
| 2975 |
Request Header Value |
|
| 2977 | 2976 |
============== ========================= |
| 2978 | 2977 |
X-Auth-Token User authentication token |
| 2979 |
Content-Type Type or request body
|
|
| 2980 |
Content-Length Length of request body
|
|
| 2978 |
Content-Type Type or request body |
|
| 2979 |
Content-Length Length of request body |
|
| 2981 | 2980 |
============== ========================= |
| 2982 | 2981 |
|
| 2983 | 2982 |
**Example Request Headers**:: |
| ... | ... | |
| 3034 | 3033 |
| |
| 3035 | 3034 |
|
| 3036 | 3035 |
============== ========================= |
| 3037 |
Request Header Value
|
|
| 3036 |
Request Header Value |
|
| 3038 | 3037 |
============== ========================= |
| 3039 | 3038 |
X-Auth-Token User authentication token |
| 3040 |
Content-Type Type or request body
|
|
| 3041 |
Content-Length Length of request body
|
|
| 3039 |
Content-Type Type or request body |
|
| 3040 |
Content-Length Length of request body |
|
| 3042 | 3041 |
============== ========================= |
| 3043 | 3042 |
|
| 3044 | 3043 |
**Example Request Headers**:: |
Also available in: Unified diff