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/reference/blobs/server.rst | 63 ++++++----------------------------------- 1 file changed, 9 insertions(+), 54 deletions(-) (limited to 'docs/reference/blobs/server.rst') diff --git a/docs/reference/blobs/server.rst b/docs/reference/blobs/server.rst index 532fccd7..cda0b95c 100644 --- a/docs/reference/blobs/server.rst +++ b/docs/reference/blobs/server.rst @@ -1,68 +1,23 @@ Server-side blobs ================= +The server-side implementation of blobs provides HTTP APIs for data storage +using a filesystem backend. + +HTTP APIs +--------- + Soledad Server provides two different REST APIs for interacting with blobs: -* A public **HTTP Blobs API**, providing the *Blobs* service for Soledad Client - (i.e. actual users of the infrastructure). +* A *public* :ref:`blobs-http-api`, providing the *Blobs* service for Soledad + Client (i.e. actual users of the infrastructure). -* A local **HTTP Incoming Box API**, providing the delivery part of the +* 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. - -.. _http-blobs-api: - -HTTP Blobs 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. - - -HTTP Incoming Box 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``. - - .. _filesystem-backend: Filesystem backend -- cgit v1.2.3