[doc] add blobs api doc

7 files changed, 111 insertions, 13 deletions

diff --git a/docs/api/attachments.rst b/docs/api/attachments.rst
index 80b81d67..434a7526 100644
--- a/docs/api/attachments.rst
+++ b/docs/api/attachments.rst
@@ -1,5 +1,5 @@
-Client-side Attachments API
-===========================
+Document Attachments API
+========================
 
 Soledad Documents implement the ``IDocumentWithAttachment`` API that associates
 :ref:`blobs` with documents.
diff --git a/docs/api/blobs-client.rst b/docs/api/blobs-client.rst
new file mode 100644
index 00000000..b5811cc6
--- /dev/null
+++ b/docs/api/blobs-client.rst
@@ -0,0 +1,13 @@
+Blobs Client-side Python API
+============================
+
+Each Soledad Client has a property called ``blobmanager`` which is an instance
+of the ``BlobManager`` class and handles Blobs creation, retrieval, deletion
+and synchronization.
+
+.. toctree::
+   :maxdepth: 1
+
+   blobs/blobmanager
+   blobs/sync
+   blobs/errors
diff --git a/docs/api/blobs-server.rst b/docs/api/blobs-server.rst
new file mode 100644
index 00000000..3efe86bd
--- /dev/null
+++ b/docs/api/blobs-server.rst
@@ -0,0 +1,63 @@
+Blobs Server-side HTTP API
+==========================
+
+Soledad Server provides two different REST APIs for interacting with blobs:
+
+* A *public* :ref:`blobs-http-api`, providing the *Blobs* service for Soledad
+  Client (i.e. actual users of the infrastructure).
+
+* A *local* :ref:`incoming-http-api`, providing the delivery part of the
+  :ref:`incoming-box` service, currently used for the MX mail delivery.
+
+Authentication is handled differently for each of the endpoints, see
+:ref:`authentication` for more details.
+
+.. _blobs-http-api:
+
+Public Blobs HTTP API
+---------------------
+
+The *public endpoint* provides the following REST API for interacting with the
+*Blobs* service:
+
+=========================== ========== ================================= ============================================
+path                        method     action                            accepted query string fields
+=========================== ========== ================================= ============================================
+``/blobs/{uuid}``           ``GET``    Get a list of blobs. filtered by  ``namespace``, ``filter_flag``, ``order_by``
+                                       a flag.
+``/blobs/{uuid}/{blob_id}`` ``GET``    Get the contents of a blob.       ``namespace``
+``/blobs/{uuid}/{blob_id}`` ``PUT``    Create a blob. The content of the ``namespace``
+                                       blob should be sent in the body
+                                       of the request.
+``/blobs/{uuid}/{blob_id}`` ``POST``   Set the flags for a blob. A list  ``namespace``
+                                       of flags should be sent in the
+                                       body of the request.
+``/blobs/{uuid}/{blob_id}`` ``DELETE`` Delete a blob.                    ``namespace``
+=========================== ========== ================================= ============================================
+
+The Blobs service supports *namespaces*. All requests can be modified by the
+``namespace`` query string parameter, and the results will be restricted to
+a certain namespace. When no namespace explicitelly given, the ``default``
+namespace is used.
+
+When listing blobs, the results can be filtered by flag and/or ordered by date
+using the ``filter_flag`` and ``order_by`` query string parameters. The
+possible values for ``order_by`` are ``date`` or ``+date`` for increasing
+order, or ``-date`` for decreasing order.
+
+.. _incoming-http-api:
+
+Local Incoming Box HTTP API
+---------------------------
+
+The *local endpoint* provides the following REST API for interacting with the
+:ref:`incoming-box` service.
+
+============================== ========== =================================
+path                           method     action
+============================== ========== =================================
+``/incoming/{uuid}/{blob_id}`` ``PUT``    Create an incoming blob. The content of the blob should be sent in the body of the request.
+============================== ========== =================================
+
+All blobs created using this API are inserted under the namespace ``MX`` and
+flagged as ``PENDING``.
diff --git a/docs/api/blobs.rst b/docs/api/blobs.rst
deleted file mode 100644
index fbf31e1c..00000000
--- a/docs/api/blobs.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-Client-side Blobs API
-=====================
-
-The Soledad Client object has a ``blobmanager`` property which is responsible
-for handling blobs.
-
-.. autoclass:: leap.soledad.client._db.blobs.BlobManager
-   :members:
-   :special-members: __init__
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/api/blobs/blobmanager.rst b/docs/api/blobs/blobmanager.rst
new file mode 100644
index 00000000..04165a57
--- /dev/null
+++ b/docs/api/blobs/blobmanager.rst
@@ -0,0 +1,15 @@
+.. _blobmanager-api:
+
+Blobs creation, retrieval, deletion and flagging
+================================================
+
+The ``BlobManager`` class is responsible for blobs creation, retrieval,
+deletion, flagging and synchronizing. For better code organization, the methods
+related to synchronization are implemented separatelly in a superclass (see
+:ref:`blobs-sync-api`).
+
+.. autoclass:: leap.soledad.client._db.blobs.BlobManager
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/blobs/errors.rst b/docs/api/blobs/errors.rst
new file mode 100644
index 00000000..66454631
--- /dev/null
+++ b/docs/api/blobs/errors.rst
@@ -0,0 +1,6 @@
+Blobs Errors
+============
+
+.. automodule:: leap.soledad.client._db.blobs.errors
+   :members:
+   :undoc-members:
diff --git a/docs/api/blobs/sync.rst b/docs/api/blobs/sync.rst
new file mode 100644
index 00000000..53740d64
--- /dev/null
+++ b/docs/api/blobs/sync.rst
@@ -0,0 +1,12 @@
+.. _blobs-sync-api:
+
+Blobs Synchronization
+=====================
+
+The synchronization part of the ``BlobManager`` class is implemented in the
+``BlobsSynchronizer`` class, whose API can be seen below.
+
+.. autoclass:: leap.soledad.client._db.blobs.sync.BlobsSynchronizer
+   :members:
+   :special-members: __init__
+   :undoc-members: