started working on rest api docs

docs/api.rst

@@ -0,0 +1,103 @@
+The StackTach REST Interface
+############################
+
+stacky/deployments
+==================
+
+.. http:get:: /stacky/deployments/
+
+   The list of all available deployments
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /stacky/deployments HTTP/1.1
+      Host: example.com
+      Accept: application/json
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Vary: Accept
+      Content-Type: text/json
+
+      [
+        {
+          "post_id": 12345,
+          "author_id": 123,
+          "tags": ["server", "web"],
+          "subject": "I tried Nginx"
+        },
+        {
+          "post_id": 12346,
+          "author_id": 123,
+          "tags": ["html5", "standards", "web"],
+          "subject": "We go to HTML 5"
+        }
+      ]
+
+   :query sort: one of ``hit``, ``created-at``
+   :query offset: offset number. default is 0
+   :query limit: limit number. default is 30
+   :reqheader Accept: the response content type depends on
+                      :mailheader:`Accept` header
+   :reqheader Authorization: optional OAuth token to authenticate
+   :resheader Content-Type: this depends on :mailheader:`Accept`
+                            header of request
+   :statuscode 200: no error
+   :statuscode 404: there's no user
+
+
+stacky/events
+=============
+
+stacky/hosts
+============
+
+stacky/uuid
+===========
+
+stacky/timings
+==============
+
+stacky/timings/uuid
+===================
+
+stacky/summary
+==============
+
+stacky/request
+==============
+
+stacky/reports
+==============
+
+stacky/report/<report_id>
+=========================
+
+stacky/show/<event_id>
+======================
+
+stacky/watch/<deployment_id>
+============================
+
+stacky/search
+=============
+
+stacky/kpi
+==========
+
+stacky/kpi/<tenant_id>
+======================
+
+stacky/usage/launches
+=====================
+
+stacky/usage/deletes
+====================
+
+stacky/usage/exists
+===================

docs/conf.py

@@ -28,7 +28,7 @@ import os
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinxcontrib.httpdomain']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -13,6 +13,7 @@ Contents:
 
    intro
    setup
+   api
 
 
 Indices and tables

etc/pip-requires.txt

@@ -7,4 +7,5 @@ prettytable>=0.7.2
 argparse
 Pympler
 requests
-south
+south
+sphinxcontrib-httpdomain