Improve API endpoint and usage documentation

Just general improvements that felt appropriate after landing the
recent API refactor.

Change-Id: Ia345e9d7ec2f0dc38ee5bfff13c9fc7bfa206931

README.rst

@@ -38,7 +38,8 @@ What happens behind the scenes is that the ARA Ansible callback plugin used
 the built-in API client to send the data to the API which then saved it to a
 database located by default at ``~/.ara/server/ansible.sqlite``.
 
-You're now ready to start poking at the API with the built-in API clients !
+You're now ready to start poking at the API with the built-in
+`API clients <https://ara.readthedocs.io/en/feature-1.0/api-usage.html>`_ !
 
 If you'd like to have the ARA web reporting interface, take a look at
 `ara-web <https://github.com/openstack/ara-web>`_.
@@ -47,7 +48,7 @@ Documentation
 =============
 
 Documentation for installing, configuring, running and using ara is
-available on `readthedocs.io <https://ara.readthedocs.io>`_.
+available on `readthedocs.io <https://ara.readthedocs.io/en/feature-1.0/>`_.
 
 Community and getting help
 ==========================

doc/source/api-documentation.rst

@@ -0,0 +1,60 @@
+API Documentation
+=================
+
+The API documentation is a work in progress.
+
+Built-in API browser interface
+------------------------------
+
+ARA ships with a helpful interface to navigate the API directly from your
+favorite web browser.
+
+For example, if you run ``ara-manage runserver``, this interface would be
+available at ``http://127.0.0.1:8000/api/v1/``:
+
+.. image:: ../source/_static/ara-api-browser-root.png
+
+You can navigate the interface and drill down to list views, for example:
+
+.. image:: ../source/_static/ara-api-browser-playbooks.png
+
+You can also see what a detailed view looks like by querying a specific object id:
+
+.. image:: ../source/_static/ara-api-browser-playbook.png
+
+Alternatively, you may also find an up-to-date live demonstration of the API at
+``https://api.demo.recordsansible.org``.
+
+Relationship between objects
+----------------------------
+
+The relationship between objects in the API should be straightforward with an
+understanding of how Ansible playbooks are executed.
+
+Generally speaking, the data is organized in the following fashion::
+
+   labels
+     |
+  Playbook -> Play -> Task -> Result <- Host
+     |                  |       |        |
+    file               file   content   facts
+
+- Every object is associated to a playbook (except *labels* which are applied to playbooks)
+- In a playbook you have plays
+- In plays you have tasks
+- In tasks you have results
+- Results have a relationship to their parent task and the host the task ran on
+
+- Files are only associated to a playbook but tasks have a reference to the file
+  they were executed from
+- Records (provided by ``ara_record``) are only associated to a playbook
+
+Additional fields may only be available in the detailed views. For example:
+
+- Playbooks arguments with ``/api/v1/playbooks/<id>``
+- Hosts facts with ``/api/v1/hosts/<id>``
+- Results content with ``/api/v1/results/<id>``
+- Files content with ``/api/v1/files/<id>``
+
+ARA ships with two built-in API clients to help you get started. You can learn
+more about those clients in :ref:`api-usage:Using ARA API clients`.

doc/source/api-usage.rst

@@ -1,14 +1,14 @@
 Using ARA API clients
 =====================
 
-When installing ARA, you are provided with an API server and two API clients
-out of the box:
+When installing ARA, you are provided with a REST API server and two API
+clients out of the box:
 
 - ``AraOfflineClient`` can query the API without needing an API server to be running
 - ``AraHttpClient`` is meant to query a specified API server over http
 
-ARA Offline REST API client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ARA Offline API client
+~~~~~~~~~~~~~~~~~~~~~~
 
 If your use case doesn't require a remote or persistent API server, the offline
 client lets you query the API without needing to start an API server.
@@ -22,8 +22,8 @@ In order to use this client, you would instanciate it like this::
     # Instanciate the offline client
     client = AraOfflineClient()
 
-ARA HTTP REST API client
-~~~~~~~~~~~~~~~~~~~~~~~~
+ARA HTTP API client
+~~~~~~~~~~~~~~~~~~~
 
 ``AraHttpClient`` works with the same interface, methods and behavior as
 ``AraOfflineClient``.
@@ -41,12 +41,13 @@ specifying an endpoint parameter::
 Example API usage
 ~~~~~~~~~~~~~~~~~
 
-.. note::
-   API documentation is a work in progress.
+For more details on the API endpoints, see :ref:`api-documentation:API Documentation`.
 
-Once you've instanciated your client, you're ready to query the API.
+Otherwise, once you've instanciated your client, you're ready to query the API.
 
-Here's a code example to help you get started::
+Here's a code example to help you get started:
+
+.. code-block:: python
 
     #!/usr/bin/env python3
     # Import the client
@@ -59,26 +60,28 @@ Here's a code example to help you get started::
     # /api/v1/playbooks?status=failed
     playbooks = client.get("/api/v1/playbooks", status="failed")
 
-    # If there are any failed playbooks, retrieve their failed results
-    # and provide some insight.
+    # If there are any results from our query, get more information about the
+    # failure and print something helpful
+    template = "{timestamp}: {host} failed '{task}' ({task_file}:{lineno})"
     for playbook in playbooks["results"]:
-        # Retrieve results for this playbook
-        # /api/v1/results?playbook=<:id>&status=failed
-        results = client.get("/api/v1/results", playbook=playbook["id"], status="failed")
+        # Get a detailed version of the playbook that provides additional context
+        detailed_playbook = client.get("/api/v1/playbooks/%s" % playbook["id"])
 
-        # Iterate over failed results to get meaningful data back
-        for result in results["results"]:
-            # Get the task that generated this result
-            # /api/v1/tasks/<:id>
-            task = client.get(f"/api/v1/tasks/{result['task']}")
+        # Iterate through the playbook to get the context
+        # Playbook -> Play -> Task -> Result <- Host
+        for play in detailed_playbook["plays"]:
+            for task in play["tasks"]:
+                for result in task["results"]:
+                    if result["status"] in ["failed", "unreachable"]:
+                        print(template.format(
+                            timestamp=result["ended"],
+                            host=result["host"]["name"],
+                            task=task["name"],
+                            task_file=task["file"]["path"],
+                            lineno=task["lineno"]
+                        ))
 
-            # Get the file from which this task ran from
-            # /api/v1/files/<:id>
-            file = client.get(f"/api/v1/files/{task['file']}")
+Running this script would then provide an output that looks like the following::
 
-            # Get the host on which this result happened
-            # /api/v1/hosts/<:id>
-            host = client.get(f"/api/v1/hosts/{result['host']}")
-
-            # Print something useful
-            print(f"Failure on {host['name']}: '{task['name']}' ({file['path']}:{task['lineno']})")
+    2019-03-20T16:18:41.710765: localhost failed 'smoke-tests : Return false' (tests/integration/roles/smoke-tests/tasks/test-ops.yaml:25)
+    2019-03-20T16:19:17.332663: localhost failed 'fail' (tests/integration/failed.yaml:22)

doc/source/index.rst

@@ -11,6 +11,7 @@ Table of Contents
     Installing ARA <installation>
     API configuration settings and preferences <api-configuration>
     API authentication and security <api-security>
+    API endpoint documentation <api-documentation>
     API usage with built-in clients <api-usage>
     Architecture and workflows <architecture>