From 64dd8d41f08eae8dd4f793348e498c8ef3dc75b0 Mon Sep 17 00:00:00 2001
From: drebs <drebs@riseup.net>
Date: Thu, 2 Nov 2017 12:30:56 -0200
Subject: [doc] add blobs api doc

---
 docs/reference/blobs/client.rst | 49 ++++++++++++++++++++++++++++++++---------
 1 file changed, 38 insertions(+), 11 deletions(-)

(limited to 'docs/reference/blobs/client.rst')

diff --git a/docs/reference/blobs/client.rst b/docs/reference/blobs/client.rst
index 75c3d997..734866fe 100644
--- a/docs/reference/blobs/client.rst
+++ b/docs/reference/blobs/client.rst
@@ -1,20 +1,47 @@
 Client-side blobs
 =================
 
-On the client-side, blobs can be managed using the BlobManager API.  The
-BlobManager is responsible for managing storage of blobs both in local and
-remote storages
+Data storage
+------------
+
+On the client-side, blobs can be managed using the ``BlobManager`` API, which
+is responsible for managing storage of blobs both in local and remote storages.
+See :ref:`blobmanager-api` and :ref:`blobs-sync-api` for information on the
+client-side API.
 
 All data is stored locally in the ``blobs`` table of a SQLCipher database
 called ``{uuid}_blobs.db`` that lies in the same directory as the Soledad
-Client's JSON documents database. Both databases are encrypted with the same
-symmetric secret. All actions performed locally are mirrored remotelly using
-the :ref:`http-blobs-api`.
-
-The BlobManager supports *namespaces* and *flags* and can list local and remote
-blobs, possibly filtering by flags and ordering by date (increasingly or
-decreasingly). It has helper methods to send or fetch all missing blobs, thus
-aiding in synchronization of local and remote data.
+Client's JSON documents database (see :ref:`client-databases`). All actions
+performed locally are mirrored remotelly using the :ref:`blobs-http-api`.
+
+Namespaces
+----------
+
+The Blobs API supports **namespaces** so that applications can store and fetch
+blobs without interfering in each another. Namespaces are also used to
+implement the server-side :ref:`incoming-http-api`, used for mail delivery. All
+methods that deal with blobs storage, transfer and flagging provide
+a `namespace` parameter. If no namespace is given, the value `default` is used.
+
+Remote flags
+------------
+
+In order to allow clients to control the processing of blobs that are delivered
+by external applications, the Blobs API has the concept of **remote flags**.
+The client can get and set the following flags for Blobs that reside in the
+server: ``PENDING``, ``PROCESSING``, ``PROCESSED``, and ``FAILED``.
+
+Remote listing
+--------------
+
+The client can obtain a list of blobs in the server side so it can compare with
+its own local list and queue up blobs for download and upload. The remote
+listing can be ordered by *upload date* and filtered by *namespace* and *flag*.
+The listing can also only return the number of matches instead of the whole
+content.
+
+Client-side encryption
+----------------------
 
 When uploading, the content of the blob is encrypted with a symmetric secret
 prior to being sent to the server. When downloading, the content of the blob is
-- 
cgit v1.2.3