Documentation fixes and clarification

- In README, refer to “install.rst”, not “install.html”
- In rapi.rst, wrap line longer than 72 characters
- In rlib2.py, update and clarify description of POST vs. PUT

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

diff --git a/README b/README
index 744c6bc..c89d5bb 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
 Ganeti 2.5
 ==========
 
-For installation instructions, read the INSTALL and the doc/install.html
+For installation instructions, read the INSTALL and the doc/install.rst
 files.
 
 For a brief introduction, read the ganeti(7) manpage and the other pages

diff --git a/doc/rapi.rst b/doc/rapi.rst
index 84281f2..9a15e90 100644 (file)
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -53,8 +53,8 @@ Example::
 
 
 .. [#pwhash] Using the MD5 hash of username, realm and password is
-   described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 and
-   3.3. The reason for using it over another algorithm is forward
+   described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
+   and 3.3. The reason for using it over another algorithm is forward
    compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
    authentication in the future, the same hash could be used.
    In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote

diff --git a/lib/rapi/rlib2.py b/lib/rapi/rlib2.py
index db004f1..ab54c25 100644 (file)
--- a/lib/rapi/rlib2.py
+++ b/lib/rapi/rlib2.py
@@ -19,21 +19,35 @@
 # 02110-1301, USA.
 
 
-"""Remote API version 2 baserlib.library.
-
-  PUT or POST?
-  ============
-
-  According to RFC2616 the main difference between PUT and POST is that
-  POST can create new resources but PUT can only create the resource the
-  URI was pointing to on the PUT request.
-
-  To be in context of this module for instance creation POST on
-  /2/instances is legitim while PUT would be not, due to it does create a
-  new entity and not just replace /2/instances with it.
-
-  So when adding new methods, if they are operating on the URI entity itself,
-  PUT should be prefered over POST.
+"""Remote API resource implementations.
+
+PUT or POST?
+============
+
+According to RFC2616 the main difference between PUT and POST is that
+POST can create new resources but PUT can only create the resource the
+URI was pointing to on the PUT request.
+
+In the context of this module POST on ``/2/instances`` to chance an existing
+entity is legitimate, while PUT would not be. PUT creates a new entity (e.g. a
+new instance) with a name specified in the request.
+
+Quoting from RFC2616, section 9.6:
+
+  The fundamental difference between the POST and PUT requests is reflected in
+  the different meaning of the Request-URI. The URI in a POST request
+  identifies the resource that will handle the enclosed entity. That resource
+  might be a data-accepting process, a gateway to some other protocol, or a
+  separate entity that accepts annotations. In contrast, the URI in a PUT
+  request identifies the entity enclosed with the request -- the user agent
+  knows what URI is intended and the server MUST NOT attempt to apply the
+  request to some other resource. If the server desires that the request be
+  applied to a different URI, it MUST send a 301 (Moved Permanently) response;
+  the user agent MAY then make its own decision regarding whether or not to
+  redirect the request.
+
+So when adding new methods, if they are operating on the URI entity itself,
+PUT should be prefered over POST.
 
 """