commit 2cad4b910c5305fb3db813e6321bee41bd500fa7
Author: Iustin Pop <iustin@google.com>
Date:   Fri Jun 19 15:20:30 2009 +0200

    Update RAPI docs for the dry-run mode
    
    Signed-off-by: Iustin Pop <iustin@google.com>
    Reviewed-by: Guido Trotter <ultrotter@google.com>

diff --git a/doc/rapi.rst b/doc/rapi.rst
index 8138637..941ec0f 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -25,6 +25,31 @@ principle.
 .. _JSON: http://www.json.org/
 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
 
+Generic parameters
+------------------
+
+A few parameter mean the same thing across all resources which implement it.
+
+``bulk``
+++++++++
+
+Bulk-mode means that for the resources which usually return just a
+list of child resources (e.g. ``/2/instances`` which returns just
+instance names), the output will instead contain detailed data for all
+these subresources. This is more efficient than query-ing the
+sub-resources themselves.
+
+``dry-run``
++++++++++++
+
+The optional *dry-run* argument, if provided and set to a positive
+integer value (e.g. ``?dry-run=1``), signals to Ganeti that the job
+should not be executed, only the pre-execution checks will be done.
+
+This is useful in trying to determine (without guarantees though, as
+in the meantime the cluster state could have changed) if the operation
+is likely to succeed or at least start executing.
+
 Usage examples
 --------------
 
@@ -58,10 +83,10 @@ Python
 JavaScript
 ++++++++++
 
-.. warning:: While it's possible to use JavaScript, it poses several potential
-  problems, including browser blocking request due to
-  non-standard ports or different domain names. Fetching the data
-  on the webserver is easier.
+.. warning:: While it's possible to use JavaScript, it poses several
+  potential problems, including browser blocking request due to
+  non-standard ports or different domain names. Fetching the data on
+  the webserver is easier.
 
 .. highlight:: javascript
 
@@ -171,7 +196,6 @@ It supports the following commands: ``GET``, ``POST``.
 
 Returns a list of all available instances.
 
-
 Example::
 
     [
@@ -224,6 +248,12 @@ Example::
 
 Creates an instance.
 
+If the optional *dry-run* argument is provided and set to a positive
+integer valu (e.g. ``?dry-run=1``), the job will not be actually
+executed, only the pre-execution checks will be done. Query-ing the
+job result will return, in both dry-run and normal case, the list of
+nodes selected for the instance.
+
 Returns: a job ID that can be used later for polling.
 
 ``/2/instances/[instance_name]``
@@ -244,6 +274,8 @@ the instance list.
 
 Deletes an instance.
 
+It supports the ``dry-run`` argument.
+
 
 ``/2/instances/[instance_name]/reboot``
 +++++++++++++++++++++++++++++++++++++++
@@ -260,6 +292,9 @@ Reboots the instance.
 The URI takes optional ``type=hard|soft|full`` and
 ``ignore_secondaries=False|True`` parameters.
 
+It supports the ``dry-run`` argument.
+
+
 ``/2/instances/[instance_name]/shutdown``
 +++++++++++++++++++++++++++++++++++++++++
 
@@ -272,6 +307,8 @@ It supports the following commands: ``PUT``.
 
 Shutdowns an instance.
 
+It supports the ``dry-run`` argument.
+
 
 ``/2/instances/[instance_name]/startup``
 ++++++++++++++++++++++++++++++++++++++++
@@ -288,6 +325,9 @@ Startup an instance.
 The URI takes an optional ``force=False|True`` parameter to start the
 instance if even if secondary disks are failing.
 
+It supports the ``dry-run`` argument.
+
+
 ``/2/instances/[instance_name]/tags``
 +++++++++++++++++++++++++++++++++++++
 
@@ -312,6 +352,9 @@ 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.
 
+It supports the ``dry-run`` argument.
+
+
 ``DELETE``
 ~~~~~~~~~~
 
@@ -322,6 +365,9 @@ addressed to URI like::
 
     /tags?tag=[tag]&tag=[tag]
 
+It supports the ``dry-run`` argument.
+
+
 ``/2/jobs``
 +++++++++++
 
@@ -436,6 +482,8 @@ 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.
 
+It supports the ``dry-run`` argument.
+
 ``DELETE``
 ~~~~~~~~~~
 
@@ -446,6 +494,9 @@ addressed to URI like::
 
     /tags?tag=[tag]&tag=[tag]
 
+It supports the ``dry-run`` argument.
+
+
 ``/2/os``
 +++++++++
 
@@ -490,6 +541,9 @@ 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.
 
+It supports the ``dry-run`` argument.
+
+
 ``DELETE``
 ~~~~~~~~~~
 
@@ -500,6 +554,9 @@ addressed to URI like::
 
     /tags?tag=[tag]&tag=[tag]
 
+It supports the ``dry-run`` argument.
+
+
 ``/version``
 ++++++++++++
 
