[doc] add api doc for blobs backend

3 files changed, 163 insertions, 30 deletions

diff --git a/docs/api.rst b/docs/api.rst
index a184c9f7..31d8b36a 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -8,3 +8,4 @@ API Reference
    api/attachments
    api/blobs-client
    api/blobs-server
+   api/blobs-server-backend
diff --git a/docs/api/blobs-server-backend.rst b/docs/api/blobs-server-backend.rst
new file mode 100644
index 00000000..5a9e1033
--- /dev/null
+++ b/docs/api/blobs-server-backend.rst
@@ -0,0 +1,21 @@
+Blobs Server-side Data Backend API
+==================================
+
+Blobs Backend Interface
+-----------------------
+
+.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :show-inheritance:
+
+
+Incoming Box Backend Interface
+------------------------------
+
+.. autoclass:: leap.soledad.server.interfaces.IIncomingBoxBackend
+   :members:
+   :undoc-members:
+   :special-members: __init__
+   :show-inheritance:
diff --git a/src/leap/soledad/server/interfaces.py b/src/leap/soledad/server/interfaces.py
index 5e586ade..9a64ee76 100644
--- a/src/leap/soledad/server/interfaces.py
+++ b/src/leap/soledad/server/interfaces.py
@@ -22,86 +22,197 @@ from zope.interface import Interface
 class IBlobsBackend(Interface):
 
     """
-    An interface for a BlobsBackend.
+    An interface for a backend that can store blobs.
+
+    Classes that implement this interface are supposed to be used by
+    ``BlobsResource``, which is a ``twisted.web.resource.Resource`` that serves
+    the Blobs API. Because of that, their methods receive instances of
+    ``twisted.web.server.Request`` and should use them to serve the Blobs API.
     """
 
     def read_blob(user, blob_id, request, namespace=''):
         """
-        Read blob with a given blob_id, and write it to the passed request.
+        Read a blob from the backend storage and write it as a response to a
+        request.
+
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
 
-        :returns: a deferred that fires upon finishing.
+        :return: Either ``server.NOT_DONE_YET`` to indicate an asynchronous
+            operation or a ``bytes`` instance to write as the response to the
+            request. If ``NOT_DONE_YET`` is returned, at some point later (for
+            example, in a Deferred callback) call ``request.write(b"data")`` to
+            write data to the request, and ``request.finish()`` to send the
+            data to the browser.
         """
 
     def write_blob(user, blob_id, request, namespace=''):
         """
-        Write blob to the storage, reading it from the passed request.
+        Write a blob to the backend storage after reading it from a request.
+
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
 
-        :returns: a deferred that fires upon finishing.
+        :return: A deferred that fires when the blob has been written to the
+                 backend storage.
         """
 
     def delete_blob(user, blob_id, namespace=''):
         """
-        Delete the given blob_id.
+        Delete a blob from the backend storage.
+
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
         """
 
     def get_blob_size(user, blob_id, namespace=''):
         """
-        Get the size of the given blob id.
+        Get the size of a blob.
+
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
+
+        :return: The size of the blob.
+        :rtype: int
         """
 
     def count(user, request, namespace=''):
         """
-        Counts the total number of blobs.
+        Count the total number of blobs.
+
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: Restrict the count to a certain namespace.
+        :type namespace: str
+
+        :return: The number of blobs in the backend storage, possibly
+                 restricted to a certain namespace.
+        :rtype: int
         """
 
-    def list_blobs(user, request, namespace='', order_by=None):
+    def list_blobs(user, request, namespace='', order_by=None, deleted=False,
+                   filter_flag=None):
         """
-        Returns a json-encoded list of ids from user's blobs storage,
-        optionally ordered by order_by parameter and optionally restricted by
-        namespace.
+        List the blobs stored in the backend.
+
+        The resulting list can be ordered by date, filtered by namespace or
+        flag, and include deleted items or not.
 
-        :returns: a deferred that fires upon finishing.
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: Restrict the count to a certain namespace.
+        :type namespace: str
+
+        :param order_by: 'date' (equivalent to '+date') or  '-date', to sort
+            ascending or descending by date, respectivelly.
+        :type order_by: str
+        :param deleted: Whether to include deleted items in the result.
+        :type deleted: bool
+        :param filter_flag: If given, only results flagged with that flag will
+            be returned.
+        :type filter_flag: str
+
+        :return: A JSON list of blob ids, optionally ordered and/or restricted
+                 by namespace.
+        :rtype: str
         """
 
     def get_total_storage(user):
         """
         Get the size used by a given user as the sum of all the blobs stored
-        unders its namespace.
+        under all that user's namespaces.
+
+        :param user: The id of a user.
+        :type user: str
+
+        :return: The size in units of 1024 bytes.
+        :rtype: int
         """
 
     def add_tag_header(user, blob_id, request, namespace=''):
         """
-        Adds a header 'Tag' to the passed request object, containing the last
-        16 bytes of the encoded blob, which according to the spec contains the
-        tag.
+        Add a ``Tag`` HTTP header to the passed request containing the tag of
+        a blob.
 
-        :returns: a deferred that fires upon finishing.
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
         """
 
 
 class IIncomingBoxBackend(Interface):
 
     """
-    An interface for an IncomingBoxBackend implementation.
+    An interface for a backend that can deliver
     """
 
     def get_flags(user, blob_id, request, namespace=''):
         """
-        Given a blob_id, return it's associated flags.
+        Get the flags for a blob.
 
-        :returns: a JSON encoded string with a list of flags.
-        """
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
 
-    def set_flags(self, user, blob_id, request, namespace=''):
-        """
-        Set flags for a blob_id.
+        :return: a JSON encoded string with a list of flags.
+        :rtype: str
         """
 
-    def list_blobs(self, user, request, namespace='', order_by=None,
-                   filter_flag=False):
+    def set_flags(user, blob_id, request, namespace=''):
         """
-        Blobs listing with flags support. Accepts a filter_flag parameter,
-        which is a flag that can be used to filter results matching it.
+        Set flags for a blob.
+
+        The flags are expected to be send in the body of the request, as a JSON
+        list of strings.
+
+        :param user: The id of the user who owns the blob.
+        :type user: str
+        :param blob_id: The id of the blob.
+        :type blob_id: str
+        :param request: A representation of all of the information about the
+            request that is being made.
+        :type request: twisted.web.server.Request
+        :param namespace: An optional namespace for the blob.
+        :type namespace: str
 
-        :returns: a deferred that fires upon finishing.
+        :return: A string describing an error or ``None`` in case of success.
+        :rtype: str
         """