Merge branch '1.4'

docs/userguide/api/core.rst

@@ -5,43 +5,36 @@ Product
 -------
 
 .. http:get:: /api/v1/product
+.. http:post:: /api/v1/product
+.. http:delete:: /api/v1/product/<id>
+.. http:put:: /api/v1/product/<id>
 
-    Return a list of products and the product versions it owns.
+Filtering
+^^^^^^^^^
 
-
-    :format: (required) The API **always** requires a value of ``json`` for this
-        field.
-    :name: (optional) The name of the product to filter on.
-    :limit: (optional) Defaults to 20 items, but can be set higher or lower.  0
-        will return all records.
-
-    **Example request**:
+    :name: The name of the product to filter on.
 
     .. sourcecode:: http
 
-        GET /api/v1/product/?format=json
+        GET /api/v1/product/?format=json&name=Firefox
 
 
 Product Version
 ---------------
 
 .. http:get:: /api/v1/productversion
+.. http:post:: /api/v1/productversion
+.. http:delete:: /api/v1/productversion/<id>
+.. http:put:: /api/v1/productversion/<id>
 
-    Return a list of product versions.
-
-    .. note::
-
-        The underscores in query params (like ``case__suites``) are **DOUBLE**
-        underscores.
+Filtering
+^^^^^^^^^
 
-    :format: (required) The API **always** requires a value of ``json`` for this
-        field.
-    :version: (optional) The ProductVersion ``name`` to filter
+    :version: The ProductVersion ``name`` to filter
         on.  For example, if the Product and Version are ``Firefox 10`` then
         the ``version`` would be ``10``.
-    :product__name: (optional) The Product ``name`` to filter on.
-    :limit: (optional) Defaults to 20 items, but can be set higher or lower.  0
-        will return all records.
+    :product: The Product ``id`` to filter on.
+    :product__name: The Product ``name`` to filter on.
 
     **Example request**:
 

docs/userguide/api/environments.rst

@@ -1,18 +1,15 @@
 Environment API
-================
+===============
 
 Environment
 -----------
 
 .. http:get:: /api/v1/environment
 
-    Return a list of environments with all elements and categories.
+Filtering
+^^^^^^^^^
 
-    :format: (required) The API **always** requires a value of ``json`` for this
-        field.
     :elements: (optional) The Element ID to filter on.
-    :limit: (optional) Defaults to 20 items, but can be set higher or lower.  0
-        will return all records.
 
     **Example request**:
 

docs/userguide/api/execution.rst

@@ -4,34 +4,86 @@ Test Runs API
 Test Run
 --------
 
-.. http:get:: /api/v1/run
-
-    Return a list of test runs
+The Test Run (and related) API has some special handling that differs from the
+standard APIs.  This is because there is complex logic for submitting results,
+and new runs with results can be submitted.
 
-    .. note::
+Please consider `MozTrap Connect`_ as a way to submit results for tests.  You
+can also check out `MozTrap Connect on github`_.
 
-        Requires an API key in the header.  You must request this API key
-        from your MozTrap admin.  It is generated in the User edit page.
-        ``username=foo&api_key=bar``
+.. _MozTrap Connect on github: https://github.com/camd/moztrap-connect/
+.. _MozTrap Connect: https://moztrap-connect.readthedocs.org/en/latest/index.html
 
-    .. note::
 
-        The underscores in query params (like ``case__suites``) are **DOUBLE**
-        underscores.
+.. http:get:: /api/v1/run
+.. http:post:: /api/v1/run
 
-    :format: (required) The API **always** requires a value of ``json`` for this
-        field.
     :productversion: (optional) The ProductVersion ID to filter on.
     :productversion__version: (optional) The ProductVersion ``name`` to filter
         on.  For example, if the Product and Version are ``Firefox 10`` then
         the ``productversion__version`` would be ``10``.
     :productversion__product__name: (optional) The Product ``name`` to filter on.
     :status: (optional) The status of the run.  One of ``active`` or ``draft``.
-    :limit: (optional) Defaults to 20 items, but can be set higher or lower.  0
-        will return all records.
 
     **Example request**:
 
     .. sourcecode:: http
 
         GET /api/v1/run/?format=json&productversion__version=10&case__suites__name=Sweet%20Suite
+
+
+Run Case Versions
+-----------------
+
+.. http:get:: /api/v1/runcaseversion
+
+Filtering
+^^^^^^^^^
+
+    :run: The ``id`` of the run
+    :run__name: The ``name`` of the run
+    :caseversion: The ``id`` of the caseversion
+    :caseversion__name: The ``name`` of the caseversion
+
+    .. sourcecode:: http
+
+        GET /api/v1/product/?format=json&run__name=runfoo
+
+
+Results
+-------
+
+.. http:patch:: /api/v1/result
+
+    **Example request**:
+    This endpoint is write only.  The submitted result objects should
+    be formed like this:
+
+    .. sourcecode:: http
+
+        {
+            "objects": [
+                {
+                    "case": "1",
+                    "environment": "23",
+                    "run_id": "1",
+                    "status": "passed"
+                },
+                {
+                    "case": "14",
+                    "comment": "why u no make sense??",
+                    "environment": "23",
+                    "run_id": "1",
+                    "status": "invalidated"
+                },
+                {
+                    "bug": "http://www.deathvalleydogs.com",
+                    "case": "326",
+                    "comment": "why u no pass?",
+                    "environment": "23",
+                    "run_id": "1",
+                    "status": "failed",
+                    "stepnumber": 1
+                }
+            ]
+        }

docs/userguide/api/index.rst

@@ -1,13 +1,85 @@
 REST API
 ========
 
-These are the REST endpoints available to MozTrap.
+These are the REST endpoints available to MozTrap.  These are build using the
+`TastyPie`_ package, so please also refer to the TastyPie documentation for more
+info.
+
+.. _TastyPie: http://django-tastypie.readthedocs.org/en/latest/resources.html
+
+General
+-------
+
+The general format for all rest endpoints is:
+
+.. http:get:: /api/v1/<object_type>/
+
+    Return a list of objects
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        GET /api/v1/product/?format=json&limit=50
+
+.. http:get:: /api/v1/<object_type/<id>/
+
+    Return a single object
+
+.. http:post:: /api/v1/<object_type>/
+
+    Create one or more items.  **requires** :ref:`API key<api-key>`
+
+.. http:put:: /api/v1/<object_type>/<id>
+
+    Update one item.  **requires** :ref:`API key<api-key>`
+
+.. http:delete:: /api/v1/<object_type>/<id>
+
+    Delete one item.  **requires** :ref:`API key<api-key>`
+
+.. note::
+
+    * POST does not replace the whole list of items, it only creates new ones
+    * DELETE on a list is not supported
+    * PUT to a list is not supported
+
+
+Query Parameters
+----------------
+
+* See each individual :ref:`Object Types<object-types>` for the params it
+  supports.
+* See `TastyPie Filtering`_ for more info on query parameters.
+
+.. _TastyPie Filtering: http://django-tastypie.readthedocs.org/en/latest/resources.html#basic-filtering
+
+
+Some fields are universal to all requests and :ref:`Object Types<object-types>`:
+
+* **format** (required) The API **always** requires a value of ``json`` for
+    this field.
+* **limit** (optional) Defaults to 20 items, but can be set higher or lower.
+    0 will return all records.
+
+
+.. note::
+
+    The underscores in query param fields (like ``case__suites``) are **DOUBLE**
+    underscores.
+
+
+.. _object-types:
+
+Supported Object Types
+----------------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    core
    library
    execution
    environments
    tags
+   key

docs/userguide/api/key.rst

@@ -0,0 +1,12 @@
+.. _api-key:
+
+API Keys
+========
+
+API Keys are generated on the ``Manage | Users`` page for a user.  Only an
+:ref:`Admin<admin-role>` can create an API Key for a user.
+
+The API key is passed on the query string for an API like this::
+
+    ``POST /api/v1/product?username=camd&api_key=abc123``
+