Commit c8e0a534 authored by Iustin Pop's avatar Iustin Pop

Doc fixes for RAPI

After moving the documentation from the .py files to .rst, we had some
cleanups to do.

This fixes the formatting of the comments, improves them a little, and
removes deprecated info (DOC_URI) from the python source.
Signed-off-by: default avatarIustin Pop <iustin@google.com>
Reviewed-by: default avatarGuido Trotter <ultrotter@google.com>
parent c1be3f59
Ganeti remote API
=================
Documents Ganeti version 2.0
Documents Ganeti version |version|
.. contents::
......@@ -34,9 +34,11 @@ long as it supports network connections.
Shell
+++++
.. highlight:: sh
Using wget::
wget -q -O - https://CLUSTERNAME:5080/2/info
wget -q -O - https://CLUSTERNAME:5080/2/info
or curl::
......@@ -46,7 +48,7 @@ or curl::
Python
++++++
::
.. highlight: python
import urllib2
f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
......@@ -61,6 +63,8 @@ JavaScript
non-standard ports or different domain names. Fetching the data
on the webserver is easier.
.. highlight:: javascript
::
var url = 'https://CLUSTERNAME:5080/2/info';
......@@ -82,59 +86,49 @@ JavaScript
Resources
---------
/
+
::
/ resource.
It supports the following commands: GET.
.. highlight:: javascript
GET
~~~
``/``
+++++
::
The root resource.
Show the list of mapped resources.
It supports the following commands: ``GET``.
Returns: a dictionary with 'name' and 'uri' keys for each of them.
``GET``
~~~~~~~
/2
++
Shows the list of mapped resources.
::
Returns: a dictionary with 'name' and 'uri' keys for each of them.
/2 resource, the root of the version 2 API.
``/2``
++++++
It supports the following commands: GET.
The ``/2`` resource, the root of the version 2 API.
GET
~~~
It supports the following commands: ``GET``.
::
``GET``
~~~~~~~
Show the list of mapped resources.
Show the list of mapped resources.
Returns: a dictionary with 'name' and 'uri' keys for each of them.
Returns: a dictionary with ``name`` and ``uri`` keys for each of them.
/2/info
+++++++
``/2/info``
+++++++++++
::
Cluster information resource.
Cluster info.
It supports the following commands: ``GET``.
It supports the following commands: GET.
``GET``
~~~~~~~
GET
~~~
Returns cluster information.
::
Returns cluster information.
Example::
Example::
{
"config_version": 2000000,
......@@ -165,24 +159,20 @@ GET
}
}
/2/instances
++++++++++++
::
``/2/instances``
++++++++++++++++
/2/instances resource.
The instances resource.
It supports the following commands: GET, POST.
It supports the following commands: ``GET``, ``POST``.
GET
~~~
``GET``
~~~~~~~
::
Returns a list of all available instances.
Returns a list of all available instances.
Example::
Example::
[
{
......@@ -195,11 +185,11 @@ GET
}
]
If the optional 'bulk' argument is provided and set to 'true'
value (i.e '?bulk=1'), the output contains detailed
information about instances as a list.
If the optional *bulk* argument is provided and set to a true value
(i.e ``?bulk=1``), the output contains detailed information about
instances as a list.
Example::
Example::
[
{
......@@ -228,216 +218,166 @@ GET
...
]
Returns: a dictionary with 'name' and 'uri' keys for each of them.
POST
~~~~
::
Create an instance.
Returns: a job id
/2/instances/[instance_name]
++++++++++++++++++++++++++++
::
/2/instances/[instance_name] resources.
It supports the following commands: GET, DELETE.
GET
~~~
::
Send information about an instance.
DELETE
~~~~~~
::
Delete an instance.
/2/instances/[instance_name]/reboot
+++++++++++++++++++++++++++++++++++
::
/2/instances/[instance_name]/reboot resource.
Implements an instance reboot.
It supports the following commands: POST.
POST
~~~~
::
Reboot an instance.
The URI takes type=[hard|soft|full] and
ignore_secondaries=[False|True] parameters.
``POST``
~~~~~~~~
/2/instances/[instance_name]/shutdown
+++++++++++++++++++++++++++++++++++++
Creates an instance.
::
Returns: a job ID that can be used later for polling.
/2/instances/[instance_name]/shutdown resource.
``/2/instances/[instance_name]``
++++++++++++++++++++++++++++++++
Implements an instance shutdown.
Instance-specific resource.
It supports the following commands: PUT.
It supports the following commands: ``GET``, ``DELETE``.
PUT
~~~
``GET``
~~~~~~~
::
Returns information about an instance, similar to the bulk output from
the instance list.
Shutdown an instance.
``DELETE``
~~~~~~~~~~
Deletes an instance.
/2/instances/[instance_name]/startup
++++++++++++++++++++++++++++++++++++
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
::
Reboots URI for an instance.
/2/instances/[instance_name]/startup resource.
It supports the following commands: ``POST``.
Implements an instance startup.
``POST``
~~~~~~~~
It supports the following commands: PUT.
Reboots the instance.
PUT
~~~
The URI takes optional ``type=hard|soft|full`` and
``ignore_secondaries=False|True`` parameters.
::
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
Startup an instance.
Instance shutdown URI.
The URI takes force=[False|True] parameter to start the instance
if even if secondary disks are failing.
It supports the following commands: ``PUT``.
/2/instances/[instance_name]/tags
+++++++++++++++++++++++++++++++++
``PUT``
~~~~~~~
::
Shutdowns an instance.
/2/instances/[instance_name]/tags resource.
Manages per-instance tags.
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
It supports the following commands: GET, PUT, DELETE.
Instance startup URI.
GET
~~~
It supports the following commands: ``PUT``.
::
``PUT``
~~~~~~~
Returns a list of tags.
Startup an instance.
Example: ["tag1", "tag2", "tag3"]
The URI takes an optional ``force=False|True`` parameter to start the
instance if even if secondary disks are failing.
PUT
~~~
``/2/instances/[instance_name]/tags``
+++++++++++++++++++++++++++++++++++++
::
Manages per-instance tags.
Add a set of tags.
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
The request as a list of strings should be PUT to this URI. And
you'll have back a job id.
``GET``
~~~~~~~
DELETE
~~~~~~
Returns a list of tags.
::
Example::
Delete a tag.
["tag1", "tag2", "tag3"]
In order to delete a set of tags, the DELETE
request should be addressed to URI like:
/tags?tag=[tag]&tag=[tag]
``PUT``
~~~~~~~
/2/jobs
+++++++
Add a set of tags.
::
The request as a list of strings should be ``PUT`` to this URI. The
result willl be a job id.
/2/jobs resource.
``DELETE``
~~~~~~~~~~
It supports the following commands: GET.
Delete a tag.
GET
~~~
In order to delete a set of tags, the DELETE request should be
addressed to URI like::
::
/tags?tag=[tag]&tag=[tag]
Returns a dictionary of jobs.
``/2/jobs``
+++++++++++
Returns: a dictionary with jobs id and uri.
The ``/2/jobs`` resource.
/2/jobs/[job_id]
++++++++++++++++
It supports the following commands: ``GET``.
::
``GET``
~~~~~~~
/2/jobs/[job_id] resource.
Returns a dictionary of jobs.
It supports the following commands: GET, DELETE.
Returns: a dictionary with jobs id and uri.
GET
~~~
``/2/jobs/[job_id]``
++++++++++++++++++++
::
Returns a job status.
Individual job URI.
Returns: a dictionary with job parameters.
The result includes:
- id: job ID as a number
- status: current job status as a string
- ops: involved OpCodes as a list of dictionaries for each
opcodes in the job
- opstatus: OpCodes status as a list
- opresult: OpCodes results as a list of lists
It supports the following commands: ``GET``, ``DELETE``.
DELETE
~~~~~~
``GET``
~~~~~~~
::
Returns a job status.
Cancel not-yet-started job.
Returns: a dictionary with job parameters.
The result includes:
- id: job ID as a number
- status: current job status as a string
- ops: involved OpCodes as a list of dictionaries for each
opcodes in the job
- opstatus: OpCodes status as a list
- opresult: OpCodes results as a list of lists
/2/nodes
++++++++
``DELETE``
~~~~~~~~~~
::
Cancel a not-yet-started job.
/2/nodes resource.
``/2/nodes``
++++++++++++
It supports the following commands: GET.
Nodes resource.
GET
~~~
It supports the following commands: ``GET``.
::
``GET``
~~~~~~~
Returns a list of all nodes.
Returns a list of all nodes.
Example::
Example::
[
{
......@@ -450,11 +390,11 @@ GET
}
]
If the optional 'bulk' argument is provided and set to 'true'
value (i.e '?bulk=1'), the output contains detailed
information about nodes as a list.
If the optional 'bulk' argument is provided and set to 'true' value
(i.e '?bulk=1'), the output contains detailed information about nodes
as a list.
Example::
Example::
[
{
......@@ -472,143 +412,106 @@ GET
...
]
Returns: a dictionary with 'name' and 'uri' keys for each of them
/2/nodes/[node_name]/tags
+++++++++++++++++++++++++
::
/2/nodes/[node_name]/tags resource.
Manages per-node tags.
It supports the following commands: GET, PUT, DELETE.
GET
~~~
::
Returns a list of tags.
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
Example: ["tag1", "tag2", "tag3"]
Manages per-node tags.
PUT
~~~
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
::
``GET``
~~~~~~~
Add a set of tags.
Returns a list of tags.
The request as a list of strings should be PUT to this URI. And
you'll have back a job id.
Example::
DELETE
~~~~~~
["tag1", "tag2", "tag3"]
::
``PUT``
~~~~~~~
Delete a tag.
In order to delete a set of tags, the DELETE
request should be addressed to URI like:
/tags?tag=[tag]&tag=[tag]
/2/os
+++++
Add a set of tags.
::
The request as a list of strings should be PUT to this URI. The result
will be a job id.
/2/os resource.
``DELETE``
~~~~~~~~~~
It supports the following commands: GET.
Deletes tags.
GET
~~~
In order to delete a set of tags, the DELETE request should be
addressed to URI like::
::
/tags?tag=[tag]&tag=[tag]
Return a list of all OSes.
``/2/os``
+++++++++
Can return error 500 in case of a problem.
OS resource.
Example: ["debian-etch"]
It supports the following commands: ``GET``.
/2/tags
+++++++
``GET``
~~~~~~~
::
Return a list of all OSes.
/2/instances/tags resource.
Can return error 500 in case of a problem. Since this is a costly
operation for Ganeti 2.0, it is not recommended to execute it too
often.
Manages cluster tags.
Example::
It supports the following commands: GET, PUT, DELETE.
["debian-etch"]
GET
~~~
``/2/tags``
+++++++++++
::
Manages cluster tags.
Returns a list of tags.
It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
Example: ["tag1", "tag2", "tag3"]
``GET``
~~~~~~~
PUT
~~~
Returns the cluster tags.
::
Example::
Add a set of tags.
["tag1", "tag2", "tag3"]
The request as a list of strings should be PUT to this URI. And
you'll have back a job id.
``PUT``
~~~~~~~
DELETE
~~~~~~
Adds a set of tags.
::
The request as a list of strings should be PUT to this URI. The result
will be a job id.
Delete a tag.
``DELETE``
~~~~~~~~~~
In order to delete a set of tags, the DELETE
request should be addressed to URI like:
/tags?tag=[tag]&tag=[tag]
Deletes tags.
/nodes/[node_name]
++++++++++++++++++
In order to delete a set of tags, the DELETE request should be
addressed to URI like::
::
/tags?tag=[tag]&tag=[tag]
/2/nodes/[node_name] resources.
It supports the following commands: GET.
GET
~~~
::
Send information about a node.
/version
++++++++
::
/version resource.
``/version``
++++++++++++
This resource should be used to determine the remote API version and
to adapt clients accordingly.
The version resource.
It supports the following commands: GET.
This resource should be used to determine the remote API version and
to adapt clients accordingly.
GET
~~~
It supports the following commands: ``GET``.
::
``GET``
~~~~~~~
Returns the remote API version.