doc: Add batch documentation, update version number.

  * Add new batch documentation and schema.
  * Bump doc version number.
  * Add status query parameters on other collection docs.

Change-Id: I9e29fb201546aa2320b50fb4074a6655171438c5

10 files changed, 186 insertions, 8 deletions

diff --git a/doc/batch-collection.rst b/doc/batch-collection.rst
new file mode 100644
index 0000000..950a4be
--- /dev/null
+++ b/doc/batch-collection.rst
@@ -0,0 +1,129 @@
+.. _collection_batch:
+
+batch
+-----
+
+This is not a real collection. It is instead used to perform a series of operations in batch: if you have more than one request to perform, instead of
+sending each request on its own, send a single batch operation request
+specifying all your requests.
+
+It works by receiving a ``POST`` request with the operations to perform.
+
+.. note::
+
+    At the moment the batch operator can perform only GET operations on
+    the available collections.
+
+GET
+***
+
+.. caution::
+    Not implemented. Will return a :ref:`status code <http_status_code>`
+    of ``501``.
+
+POST
+****
+
+.. http:post:: /batch
+
+ Perform the specified batch operations.
+
+ :reqjson array batch: The default batch operator; it is a list of objects
+    made of the keywords described below.
+ :reqjsonarr string method: The method of the request. Only ``GET`` is
+    supported.
+ :reqjsonarr string operation_id: An identification for this request opearation.
+ :reqjsonarr string collection: On which collection the request should be
+    performed.
+ :reqjsonarr string document_id: The ID of a document in the collection. For
+    the ``count`` collection, this is used to identify on which collection to
+    perform the count.
+ :reqjsonarr string query: The query to perform as a series of ``key=value``
+    pairs separated by the ampersand ("&") character. The keys must be
+    the same specified in each collections query parameters.
+ :resjsonarr int code: The HTTP code of the response.
+ :resjsonarr array result: The list of result objects for each operation in the
+    batch. If the ``operation_id`` parameter was specified, it will be included
+    in each object. Each ``result`` object in turn contains another ``result``
+    array that holds the query results.
+
+ :reqheader Authorization: The token necessary to authorize the request.
+ :reqheader Content-Type: Content type of the transmitted data, must be ``application/json``.
+ :reqheader Accept-Encoding: Accept the ``gzip`` coding.
+
+ :resheader Content-Type: Will be ``application/json; charset=UTF-8``.
+
+ :status 202: The request has been accepted and is going to be created.
+ :status 400: JSON data not valid.
+ :status 403: Not authorized to perform the operation.
+ :status 415: Wrong content type.
+ :status 422: No real JSON data provided.
+
+ **Example Requests**
+
+ .. sourcecode:: http 
+
+    POST /batch HTTP/1.1
+    Host: api.backend.linaro.org
+    Content-Type: application/json
+    Accept: */*
+    Authorization: token
+
+    {
+        "batch": [
+            {
+                "method": "GET",
+                "operation_id": "foo",
+                "collection": "count",
+                "document_id": "boot",
+                "query": "status=FAIL&job=next&date_range=5"
+            },
+            {
+                "method": "GET",
+                "operation_id": "bar",
+                "collection": "defconfig",
+                "query": "status=PASS&job=mainline&date_range=5&field=arch&field=defconfig"
+            }
+        ]
+    }
+
+ **Example Responses**
+
+ .. sourcecode:: http
+
+    HTTP/1.1 200 OK
+    Vary: Accept-Encoding
+    Date: Mon, 20 Oct 2014 11:33:24 GMT
+    Content-Type: application/json; charset=UTF-8
+
+    {
+        "code": 200,
+        "result": [
+            {
+                "operation_id": "foo",
+                "result": [
+                    {
+                        "count": 5,
+                        "collection": "boot"
+                    }
+                ]
+            },
+            {
+                "operation_id": "bar",
+                "result": [
+                    {
+                        "arch": "arm64",
+                        "defconfig": "bcm2835_defconfig",
+                        "_id": "baz"
+                    }
+                ]
+            }
+        ]
+    }
+
+DELETE
+******
+
+.. caution::
+    Not implemented. Will return a :ref:`status code <http_status_code>`
+    of ``501``.
diff --git a/doc/boot-collection.rst b/doc/boot-collection.rst
index fbcf0df..022bcbd 100644
--- a/doc/boot-collection.rst
+++ b/doc/boot-collection.rst
@@ -34,7 +34,8 @@ GET
  :query string kernel: The name of a kernel.
  :query string defconfig: The name of a defconfig.
  :query string board: The name of a board.
- :query string status: The status of the boot report.
+ :query string status: The status of the boot report. Can be one of: ``PASS``
+    or ``FAIL``.
  :query int warnings: The number of warnings in the boot report.
 
  :status 200: Resuslts found.
diff --git a/doc/collections.rst b/doc/collections.rst
index 262d5ff..749431c 100644
--- a/doc/collections.rst
+++ b/doc/collections.rst
@@ -10,3 +10,4 @@ Collections
     job-collection
     defconfig-collection
     boot-collection
+    batch-collection
diff --git a/doc/conf.py b/doc/conf.py
index 8a6191d..5ec75d6 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -52,9 +52,9 @@ copyright = u'2014, Linaro Ltd.'
 # built documents.
 #
 # The short X.Y version.
-version = '2014.08'
+version = '2014.10'
 # The full version, including alpha/beta/rc tags.
-release = '2014.08'
+release = '2014.10'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/count-collection.rst b/doc/count-collection.rst
index 79ed192..961ffc7 100644
--- a/doc/count-collection.rst
+++ b/doc/count-collection.rst
@@ -8,11 +8,8 @@ GET
 
  Count the elements in all collections or in the provided ``collection``.
 
- When using the query parameters with a provided ``collection``, the results
- will include also the fields specified and their values.
-
  :param collection: The name of the collection to get the count of.
-    Can be one of ``job``, ``defconfig``, ``boot``.
+    Can be one of ``boot``, ``defconfig``, ``job``.
  :type collection: string
 
  :reqheader Authorization: The token necessary to authorize the request.
@@ -34,6 +31,8 @@ GET
  :query string job: A job name.
  :query string job_id: A job ID (in the form of ``job``-``kernel``).
  :query string kernel: A kernel name.
+ :query string status: The status of the elements to get the count of. Can be
+    one of: ``PASS`` or ``FAIL``.
 
  :status 200: Resuslts found.
  :status 403: Not authorized to perform the operation.
diff --git a/doc/defconfig-collection.rst b/doc/defconfig-collection.rst
index e2cb692..4d83ae5 100644
--- a/doc/defconfig-collection.rst
+++ b/doc/defconfig-collection.rst
@@ -34,7 +34,8 @@ GET
  :query string kernel: The name of a kernel.
  :query string defconfig: The name of a defconfig.
  :query string arch: The architecture on which the defconfig has been built.
- :query string status: The status of the defconfig built.
+ :query string status: The status of the defconfig report. Can be one of:
+    ``PASS`` or ``FAIL``.
  :query int warnings: The number of warnings in the defconfig built.
  :query int errors: The number of errors in the defconfig built.
 
@@ -149,8 +150,10 @@ DELETE
  :resheader Content-Type: Will be ``application/json; charset=UTF-8``.
 
  :status 200: Resource deleted.
+ :status 400: JSON data not valid.
  :status 403: Not authorized to perform the operation.
  :status 404: The provided resource has not been found.
+ :status 422: No real JSON data provided.
  :status 500: Internal database error.
 
  **Example Requests**
diff --git a/doc/intro.rst b/doc/intro.rst
index e849d1c..fc8ffef 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -59,6 +59,8 @@ but the JSON response will contain an empty list.
 +-------------+--------------------------------------------------------+
 | 405         | Operation not allowed.                                 |
 +-------------+--------------------------------------------------------+
+| 415         | Wrong content type.                                    |
++-------------+--------------------------------------------------------+
 | 422         | JSON not valid or not found.                           |
 +-------------+--------------------------------------------------------+
 | 500         | Internal error.                                        |
diff --git a/doc/job-collection.rst b/doc/job-collection.rst
index 8504c81..74a54ae 100644
--- a/doc/job-collection.rst
+++ b/doc/job-collection.rst
@@ -33,6 +33,8 @@ GET
  :query string nfield: The field that should *not* be returned in the response. Can be repeated multiple times.
  :query string job: A job name.
  :query string kernel: A kernel name.
+ :query string status: The status of the job report. Can be one of: ``PASS`` or
+    ``FAIL``.
 
  :status 200: Resuslts found.
  :status 403: Not authorized to perform the operation.
diff --git a/doc/schema-batch.rst b/doc/schema-batch.rst
new file mode 100644
index 0000000..bb984d6
--- /dev/null
+++ b/doc/schema-batch.rst
@@ -0,0 +1,40 @@
+.. _schema_batch:
+
+batch
+-----
+
+A batch request object.
+
+::
+
+    {
+        "title": "batch",
+        "description": "A batch request to perform multiple operations",
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "description": "The method of the request operation as if this operation was performed in a normal HTTP request"
+                },
+                "operation_id": {
+                    "type": "string",
+                    "description": "A unique identifier for the operation to perform"
+                },
+                "collection": {
+                    "type": "string",
+                    "description": "The collection where to perform the operation"
+                },
+                "document_id": {
+                    "type": "string",
+                    "description": "The ID of the document in the collection"
+                },
+                "query": {
+                    "type": "string",
+                    "description": "A key=value pairs, separated by the ampersand character, that define the query to perform on the collection"
+                }
+            }
+        }
+    }
+
diff --git a/doc/schema.rst b/doc/schema.rst
index 294ed21..34f1c19 100644
--- a/doc/schema.rst
+++ b/doc/schema.rst
@@ -10,3 +10,4 @@ Schema
     schema-defconfig
     schema-boot
     schema-token
+    schema-batch