Implement batch api

config/readinglist.ini

@@ -8,6 +8,7 @@ readinglist.eos =
 # readinglist.basic_auth_backdoor = true
 # readinglist.backoff = 10
 readinglist.userid_hmac_secret = b4c96a8692291d88fe5a97dd91846eb4
+# readinglist.batch_max_requests = 25
 
 fxa-oauth.client_id =
 fxa-oauth.client_secret =

docs/batch.rst

@@ -0,0 +1,122 @@
+################
+Batch operations
+################
+
+.. _batch:
+
+POST /batch
+===========
+
+**Requires an FxA OAuth authentication**
+
+The POST body is a mapping, with the following attributes:
+
+- ``requests``: the list of requests
+- ``defaults``: (*optional*) values in common for all requests
+
+ Each request is a JSON mapping, with the following attribute:
+
+- ``method``: HTTP verb
+- ``path``: URI
+- ``body``: a mapping
+- ``headers``: (*optional*), otherwise take those of batch request
+
+::
+
+    {
+      "defaults": {
+        "method" : "POST",
+        "path" : "/articles",
+        "headers" : {
+          ...
+        }
+      },
+      "requests": [
+        {
+          "body" : {
+            "title": "MoFo",
+            "url" : "http://mozilla.org"
+          }
+        },
+        {
+          "body" : {
+            "title": "MoCo",
+            "url" : "http://mozilla.com"
+          }
+        },
+        {
+          "method" : "PATCH",
+          "path" : "/articles/409",
+          "body" : {
+            "read_position" : 3477
+          }
+        }
+      ]
+    ]
+
+
+The response body is a list of all responses:
+
+::
+
+    {
+      "responses": [
+        {
+          "path" : "/articles/409",
+          "status": 200,
+          "body" : {
+            "id": 409,
+            "url": "...",
+            ...
+            "read_position" : 3477
+          },
+          "headers": {
+            ...
+          }
+        },
+        {
+          "status": 201,
+          "path" : "/articles",
+          "body" : {
+            "id": 411,
+            "title": "MoFo",
+            "url" : "http://mozilla.org",
+            ...
+          },
+        },
+        {
+          "status": 201,
+          "path" : "/articles",
+          "body" : {
+            "id": 412,
+            "title": "MoCo",
+            "url" : "http://mozilla.com",
+            ...
+          },
+        },
+      ]
+    ]
+
+
+:warning:
+
+    Since the requests bodies are necessarily mappings, posting arbitrary data
+    (*like raw text or binary*)is not supported.
+
+:note:
+
+     The responses are in the same order of the requests.
+
+
+Pros & Cons
+:::::::::::
+
+* This respects REST principles
+* This is easy for the client to handle, since it just has to pile up HTTP requests while offline
+* It looks to be a convention for several REST APIs (`Neo4J <http://neo4j.com/docs/milestone/rest-api-batch-ops.html>`_, `Facebook <https://developers.facebook.com/docs/graph-api/making-multiple-requests>`_, `Parse <ttps://parse.com/docs/rest#objects-batch>`_)
+* Payload of response can be heavy, especially while importing huge collections
+* Payload of response must all be iterated to look-up errors
+
+:note:
+
+    A form of payload optimization for massive operations is planned.

docs/index.rst

@@ -19,6 +19,7 @@ Contents:
    model
    authentication
    api
+   batch
    utilities
    timestamps
    versionning

readinglist/errors.py

@@ -1,7 +1,8 @@
 import six
 from pyramid.config import global_registries
 from pyramid.httpexceptions import (
-    HTTPServiceUnavailable as PyramidHTTPServiceUnavailable, HTTPBadRequest
+    HTTPServiceUnavailable as PyramidHTTPServiceUnavailable, HTTPBadRequest,
+    HTTPInternalServerError as PyramidHTTPInternalServerError
 )
 from readinglist.utils import Enum, json
 
@@ -41,7 +42,7 @@ def format_error(code, errno, error, message=None, info=None):
 
 
 class HTTPServiceUnavailable(PyramidHTTPServiceUnavailable):
-    """Return an HTTPServiceUnavailable formatted error."""
+    """A HTTPServiceUnavailable formatted in JSON."""
 
     def __init__(self, **kwargs):
         if 'body' not in kwargs:
@@ -65,6 +66,22 @@ def __init__(self, **kwargs):
         super(HTTPServiceUnavailable, self).__init__(**kwargs)
 
 
+class HTTPInternalServerError(PyramidHTTPInternalServerError):
+    """A HTTPInternalServerError formatted in JSON."""
+
+    def __init__(self, **kwargs):
+        kwargs.setdefault('body', format_error(
+            500,
+            ERRORS.UNDEFINED,
+            "Internal Server Error",
+            "A programmatic error occured, developers have been informed.",
+            "https://github.com/mozilla-services/readinglist/issues/"))
+
+        kwargs.setdefault('content_type', 'application/json')
+
+        super(HTTPInternalServerError, self).__init__(**kwargs)
+
+
 def json_error(errors):
     """Return an HTTPError with the given status and message.
 

readinglist/tests/resource/__init__.py

@@ -1,9 +1,5 @@
-import mock
-
-from cornice import errors as cornice_errors
-
 from readinglist.backend.memory import Memory
-from readinglist.tests.support import unittest
+from readinglist.tests.support import unittest, DummyRequest
 from readinglist.resource import BaseResource
 
 
@@ -16,13 +12,8 @@ def setUp(self):
         self.resource = BaseResource(self.get_request())
 
     def get_request(self):
-        request = mock.MagicMock(headers={})
+        request = DummyRequest()
         request.db = self.db
-        request.errors = cornice_errors.Errors()
-        request.authenticated_userid = 'bob'
-        request.validated = {}
-        request.matchdict = {}
-        request.response = mock.MagicMock(headers={})
         return request
 
     @property

readinglist/tests/support.py

@@ -1,16 +1,30 @@
 import mock
 import threading
-import webtest
 
 try:
     import unittest2 as unittest
 except ImportError:
     import unittest  # NOQA
 
+from cornice import errors as cornice_errors
+import webtest
+
 from readinglist import API_VERSION
 from readinglist.utils import random_bytes_hex
 
 
+class DummyRequest(mock.MagicMock):
+    def __init__(self, *args, **kwargs):
+        super(DummyRequest, self).__init__(*args, **kwargs)
+        self.GET = {}
+        self.headers = {}
+        self.errors = cornice_errors.Errors()
+        self.authenticated_userid = 'bob'
+        self.validated = {}
+        self.matchdict = {}
+        self.response = mock.MagicMock(headers={})
+
+
 class PrefixedRequestClass(webtest.app.TestRequest):
 
     @classmethod