launchpad-reviewers team mailing list archive

["Jeroen T. Vermeulen" <jtv@xxxxxxxxxxxxx>]

Jeroen T. Vermeulen has proposed merging lp:~jtv/maas/bug-954655 into lp:maas.

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)
Related bugs:
  Bug #954655 in MAAS: "API docs do not explain how parameters are passed"
  https://bugs.launchpad.net/maas/+bug/954655

For more details, see:
https://code.launchpad.net/~jtv/maas/bug-954655/+merge/99696

Actually I was only asked to document how we pass parameters to the API.  And frankly I don't even know if I got that right.  But since I didn't even find a place to put it, I carved one out as well.

What seemed like the logical thing to do was to include the module's docstring at the top of the documentation, much like it also includes the handler methods' docstrings.

This also means that we no longer need the option to generate a header for the documentation: the header is simply included in the docstring.

Another small change I made was that the list of documentation items is no longer a list of strings including the trailing “\n” and joined directly together; instead, it's now a list of strings not including the trailing newline, which are joined together with newlines.  Most of the actual strings will still include some newlines, just no longer the trailing ones.  It's a bit inelegant to mix them that way but I find it slightly more idiomatic, and easier to read because you don't need as many “\n” sequences in the plain text.

To check out the results, “make doc”, and then read docs/api.rst; or open docs/_build/html/api.html in a browser.


Jeroen
-- 
https://code.launchpad.net/~jtv/maas/bug-954655/+merge/99696
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~jtv/maas/bug-954655 into lp:maas.

=== modified file 'src/maasserver/api.py'
--- src/maasserver/api.py	2012-03-27 10:40:40 +0000
+++ src/maasserver/api.py	2012-03-28 10:33:18 +0000
@@ -1,7 +1,52 @@
 # Copyright 2012 Canonical Ltd.  This software is licensed under the
 # GNU Affero General Public License version 3 (see the file LICENSE).
 
-"""API."""
+"""
+========
+MAAS API
+========
+
+This is the documentation for the MAAS API.  The API is "Restful"; you access
+it through normal HTTP requests.
+
+
+API versions
+------------
+
+At any given time, MAAS may support multiple versions of its API.  The version
+number is included in the API's URL, e.g. /api/1.0/
+
+For now, 1.0 is the only supported version.
+
+
+HTTP methods
+------------
+
+The following HTTP methods are available for accessing the API:
+ * GET (for information retrieval and queries),
+ * POST (for asking the system to do things),
+ * PUT (for updating objects), and
+ * DELETE (for deleting objects).
+
+All methods except DELETE may take parameters, but they are not all passed in
+the same way.  GET parameters are passed in the URL, as is normal with a GET:
+"/item/?foo=bar" passes parameter "foo" with value "bar".
+
+POST and PUT are different.  Your request should have MIME type
+"multipart/form-data"; each part represents one parameter (for POST) or
+attribute (for PUT).  Each part is named after the parameter or attribute it
+contains, and its contents are the conveyed value.
+
+All parameters are in text form.  If you need to submit binary data to the
+API, don't send it as any MIME binary format; instead, send it as a plain text
+part containing base64-encoded data.
+
+Most resources offer a choice of GET or POST operations.  In those cases these
+methods will take one special parameter, called `op`, to indicate what it is
+you want to do.
+
+For example, to list all nodes, you might GET "/api/1.0/nodes/?op=list"
+"""
 
 from __future__ import (
     print_function,
@@ -665,7 +710,16 @@
         return HttpResponse(json.dumps(value), content_type='application/json')
 
 
-def generate_api_doc(add_title=False):
+def generate_api_doc():
+    """Generate ReST documentation for the REST API.
+
+    This module's docstring forms the head of the documentation; details of
+    the API methods follow.
+
+    :return: Documentation, in ReST, for the API.
+    :rtype: :class:`unicode`
+    """
+
     # Fetch all the API Handlers (objects with the class
     # HandlerMetaClass).
     module = sys.modules[__name__]
@@ -683,21 +737,21 @@
 
     docs = [generate_doc(handler) for handler in handlers]
 
-    messages = []
-    if add_title:
-        messages.extend([
-            '**********************\n',
-            'MAAS API documentation\n',
-            '**********************\n',
-            '\n\n']
-            )
+    messages = [
+        __doc__.strip(),
+        '',
+        '',
+        'Operations',
+        '----------',
+        '',
+        ]
     for doc in docs:
         for method in doc.get_methods():
             messages.append(
-                "%s %s\n  %s\n\n" % (
+                "%s %s\n  %s\n" % (
                     method.http_name, doc.resource_uri_template,
                     method.doc))
-    return ''.join(messages)
+    return '\n'.join(messages)
 
 
 def reST_to_html_fragment(a_str):

=== modified file 'src/maasserver/management/commands/generate_api_doc.py'
--- src/maasserver/management/commands/generate_api_doc.py	2012-02-13 09:32:58 +0000
+++ src/maasserver/management/commands/generate_api_doc.py	2012-03-28 10:33:18 +0000
@@ -4,4 +4,4 @@
 
 class Command(BaseCommand):
     def handle(self, *args, **options):
-        self.stdout.write(generate_api_doc(add_title=True))
+        self.stdout.write(generate_api_doc())

=== modified file 'src/maasserver/tests/test_commands.py'
--- src/maasserver/tests/test_commands.py	2012-03-23 14:34:49 +0000
+++ src/maasserver/tests/test_commands.py	2012-03-28 10:33:18 +0000
@@ -45,7 +45,7 @@
         result = stdout.getvalue()
         # Just check that the documentation looks all right.
         self.assertIn("POST /api/1.0/account/", result)
-        self.assertIn("MAAS API documentation", result)
+        self.assertIn("MAAS API", result)
 
     def test_createadmin_requires_username(self):
         stderr = BytesIO()