From 64dd8d41f08eae8dd4f793348e498c8ef3dc75b0 Mon Sep 17 00:00:00 2001 From: drebs Date: Thu, 2 Nov 2017 12:30:56 -0200 Subject: [doc] add blobs api doc --- docs/api/attachments.rst | 4 +-- docs/api/blobs-client.rst | 13 +++++++++ docs/api/blobs-server.rst | 63 ++++++++++++++++++++++++++++++++++++++++++ docs/api/blobs.rst | 11 -------- docs/api/blobs/blobmanager.rst | 15 ++++++++++ docs/api/blobs/errors.rst | 6 ++++ docs/api/blobs/sync.rst | 12 ++++++++ 7 files changed, 111 insertions(+), 13 deletions(-) create mode 100644 docs/api/blobs-client.rst create mode 100644 docs/api/blobs-server.rst delete mode 100644 docs/api/blobs.rst create mode 100644 docs/api/blobs/blobmanager.rst create mode 100644 docs/api/blobs/errors.rst create mode 100644 docs/api/blobs/sync.rst (limited to 'docs/api') 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: -- cgit v1.2.3