diff options
Diffstat (limited to 'docs/api/blobs-server.rst')
| -rw-r--r-- | docs/api/blobs-server.rst | 63 |
1 files changed, 63 insertions, 0 deletions
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``. |