From 70a070d941a165377a0b2fd7a84bf0b443b46ea9 Mon Sep 17 00:00:00 2001 From: drebs Date: Wed, 7 Jun 2017 17:44:12 -0300 Subject: [doc] separate api in it's own section --- docs/api.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/attachments.rst | 46 +++++----------------------------------- docs/client.rst | 14 ++++++------ docs/index.rst | 2 +- docs/server.rst | 4 ++-- 5 files changed, 75 insertions(+), 51 deletions(-) create mode 100644 docs/api.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..9a725065 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,60 @@ +Soledad API +=========== + +.. contents:: + :local: + +.. _client-side-code-api: + +Client-side code API +-------------------- + +.. autoclass:: leap.soledad.client.Soledad + :members: + :undoc-members: + +.. _client-side-attachments-api: + +Client-side attachments API +--------------------------- + +.. autoclass:: leap.soledad.client._document.AttachmentStates + :members: + :undoc-members: + +.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment + :members: + :undoc-members: + + +.. _server-side-attachments-rest-api: + +Server-side attachments REST API +-------------------------------- + +These are the possible ways to interact with the attachments REST API on the +server side: + +=========== ================ ======== ================== +HTTP Method URL Content Possible responses +=========== ================ ======== ================== +GET /user_id - 200 +GET /user_id/blob_id - 200, 404 +PUT /user_id/blob_id The BLOB 200, 409, 507 +DELETE /user_id/blob_id - 200 +=========== ================ ======== ================== + +Server-side attachments code API +-------------------------------- + +.. _i-blobs-backend: + +.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend + :members: + :undoc-members: + +.. _filesystem-blobs-backend: + +.. autoclass:: leap.soledad.server._blobs.FilesystemBlobsBackend + :members: + :undoc-members: diff --git a/docs/attachments.rst b/docs/attachments.rst index 31b47a70..7435eb4f 100644 --- a/docs/attachments.rst +++ b/docs/attachments.rst @@ -30,6 +30,8 @@ database. Encryption of data before it's sent to the server is the same used for Soledad documents' content during usual synchronization process (AES-256 GCM mode). +See :ref:`client-side-attachment-api` for reference. + Usage example ^^^^^^^^^^^^^ @@ -69,17 +71,6 @@ the store that created it, and can put/get/delete an attachment: fd = yield doc.get_attachment() assert fd.read() == open('hackers.txt').read() -API -^^^ - -.. autoclass:: leap.soledad.client._document.AttachmentStates - :members: - :undoc-members: - -.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment - :members: - :undoc-members: - Server-side ----------- @@ -93,6 +84,9 @@ has to be added as an HTTP auth header, as in:: Authorization: Token +Check out the :ref:`server-side-attachments-rest-api` for more information on +how to interact with the server using HTTP. + The :ref:`IBlobsBackend ` interface is provided, so in the future there can be different ways to store attachments in the server side (think of a third-party storage, for example). Currently, the @@ -105,33 +99,3 @@ Some characteristics of the :ref:`FilesystemBlobsBackend * Configurable storage path. * Quota support. * Username, blob_id and user storage directory sanitization. - -Usage example -^^^^^^^^^^^^^ - -These are the possible ways to interact with the attachments REST API on the -server side: - -=========== ================ ======== ================== -HTTP Method URL Content Possible responses -=========== ================ ======== ================== -GET /user_id - 200 -GET /user_id/blob_id - 200, 404 -PUT /user_id/blob_id The BLOB 200, 409, 507 -DELETE /user_id/blob_id - 200 -=========== ================ ======== ================== - -API -^^^ - -.. _i-blobs-backend: - -.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend - :members: - :undoc-members: - -.. _filesystem-blobs-backend: - -.. autoclass:: leap.soledad.server._blobs.FilesystemBlobsBackend - :members: - :undoc-members: diff --git a/docs/client.rst b/docs/client.rst index ed813634..3befd69c 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -1,9 +1,9 @@ -Soledad Client API -================== +Soledad Client +============== -.. toctree:: - :maxdepth: 2 +Current reasoning about Soledad can be found `here +`_. That will be cleaned up and +migrated here in the future. -.. autoclass:: leap.soledad.client.Soledad - :members: - :undoc-members: +You can also take a look at :ref:`client-side-code-api` and +:ref:`client-side-attachments-api` for information on the API. diff --git a/docs/index.rst b/docs/index.rst index 6800ee42..45206b7e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,8 +14,8 @@ all user's devices that access a LEAP provider. :maxdepth: 2 client - attachments server + attachments Indices and tables ================== diff --git a/docs/server.rst b/docs/server.rst index 4f99f266..bec552cd 100644 --- a/docs/server.rst +++ b/docs/server.rst @@ -1,5 +1,5 @@ -Soledad Server documentation -============================ +Soledad Server +============== A U1DB server that stores data using CouchDB as its persistence layer. -- cgit v1.2.3