docs/admin.rst: added content

docs/admin.rst

@@ -1,2 +1,33 @@
 Admin API
 =========
+
+The administration API ``/admin`` helps the administrator user manage the Sachet server.
+
+An important component that is not within this endpoint is user management.
+See :ref:`user_info_api` and :ref:`user_list_api` for information about managing users.
+
+Server settings
+---------------
+
+Sachet has a server settings API::
+    
+    GET /admin/settings
+    PATCH /admin/settings
+    PUT /admin/settings
+
+Currently, server settings are represented by the following object:
+
+.. code-block:: json
+
+    {
+        "default_permissions": ["PERMISSION1", "PERMISSION2"]
+    }
+
+Anonymous permissions
+^^^^^^^^^^^^^^^^^^^^^
+
+Anonymous permissions (``default_permissions`` in the schema) are given to clients that do not authenticate.
+It is an array of strings as described by :ref:`permissions_table`.
+
+This can be useful, for example, to publish a file to the Internet.
+If the Read shares permission is enabled in anonymous permissions, anyone can read a share if given the link to it.

docs/files.rst

@@ -1,6 +1,25 @@
 Files API
 =========
 
+Overview
+--------
+The file upload process essentially works as follows:
+
+#. ``POST /files`` with the metadata to create a share.
+   This will return an URL with the share you just created.
+   (See :ref:`files_list_api`.)
+#. ``POST /files/<uuid>/content`` (the UUID is in the URL from the previous step) to upload the actual data of the share. (See :ref:`files_content_api`.)
+#. ``GET /files/<uuid>/content`` to read the share.
+
+Share modification is done with ``PUT /files/<uuid>/content``.
+
+Shares can be locked, which means they can't be modified or deleted.
+See :ref:`files_lock_api` for more information.
+
+.. note::
+
+   All data uploads are chunked: see :ref:`files_chunked_upload`.
+
 .. _files_schema:
 
 File Schema
@@ -35,7 +54,7 @@ In JSON, a file share has the following properties::
     * - ``locked``
       - Boolean
       - Read-only
-      - Shows if share is locked.
+      - Shows if share is locked (see :ref:`files_lock_api`.)
     * - ``owner_name``
       - string
       -
@@ -45,6 +64,8 @@ In JSON, a file share has the following properties::
       - Read-only
       - UUID that uniquely identifies this share.
 
+.. _files_metadata_api:
+
 Metadata API
 ------------
 
@@ -112,6 +133,38 @@ For example:
 
     The permissions from the schema that are missing here are read-only.
 
+.. _files_list_api:
+
+List API
+--------
+
+The File List API allows listing shares and creating new ones::
+
+    GET /files
+    POST /files
+
+GET
+^^^
+
+``GET /files`` is a :ref:`paginated endpoint<pagination>` that returns a list of shares.
+
+To access this endpoint, a user needs the :ref:`list shares<permissions_table>` permission.
+
+POST
+^^^^
+
+``POST /files`` creates a new share.
+The request body must conform to the :ref:`File schema<files_schema>`.
+
+To access this endpoint, a user needs the :ref:`create shares<permissions_table>` permission.
+
+.. note::
+   
+    The share created here is empty, and only contains metadata.
+    See :ref:`files_content_api` for information on uploading content.
+
+.. _files_content_api:
+
 Content API
 -----------
 
@@ -123,6 +176,40 @@ Sachet implements the following endpoints for this API::
     PUT /files/<file_uuid>/content
     GET /files/<file_uuid>/content
 
+POST
+^^^^
+
+``POST /files/<file_uuid>/content`` initializes the content of an empty share.
+This endpoint requires the :ref:`create shares<permissions_table>` permission.
+
+.. note::
+
+    You must first create a share before initializing it: see :ref:`files_list_api` for information about creation.
+
+Uploads must be chunked (see :ref:`files_chunked_upload`).
+
+To modify the contents of an existing share, use ``PUT`` instead.
+
+PUT
+^^^^
+
+``PUT /files/<file_uuid>/content`` modifies the content of an existing share.
+This endpoint requires the :ref:`modify shares<permissions_table>` permission.
+
+.. note::
+
+    You must initialize a share's content using ``POST`` before modifying it.
+
+Uploads must be chunked (see :ref:`files_chunked_upload`).
+
+GET
+^^^^
+
+``GET /files/<file_uuid>/content`` reads the contents of a share.
+This endpoint requires the :ref:`read shares<permissions_table>` permission.
+
+This endpoint supports `HTTP Range <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range>`_ headers.
+
 .. _files_chunked_upload :
 
 Chunked upload protocol
@@ -141,7 +228,7 @@ the server will instead respond with ``201 Created``.
 
 Every chunk has the following schema:
 
-.. _files_chunk_schema :
+.. _files_chunk_schema:
 
 .. code-block::
 
@@ -173,3 +260,24 @@ Every chunk has the following schema:
     * - ``upload``
       - Binary data (file)
       - Data contained in this chunk.
+
+.. _files_lock_api:
+
+Lock API
+--------
+
+Files can be locked and unlocked.
+When locked, a share can not be modified or deleted.
+
+.. note::
+
+   When attempting illegal actions on a locked share, the server will respond ``423 Locked``.
+
+The following API is used::
+
+    POST /files/<uuid>/lock
+    POST /files/<uuid>/unlock
+
+A user needs the :ref:`lock permission<permissions_table>` to access this API.
+
+To query whether a file is locked or not, see :ref:`files_metadata_api`.

docs/permissions.rst

@@ -49,7 +49,7 @@ The following is a table of permissions Sachet offers, and what they do:
       - Allows users to delete any share.
     * - Lock shares
       - ``LOCK``
-      - Allows users to lock and unlock shares.
+      - Allows users to lock and unlock shares (see :ref:`files_lock_api`).
     * - List shares
       - ``LIST``
       - Allows users to list all shares from all users.

docs/user.rst

@@ -1,14 +1,6 @@
 User API
 ========
 
-The User API allows managing users and their permissions.
-
-Sachet implements the following endpoints for this API::
-
-    GET /users/<username>
-    PATCH /users/<username>
-    PUT /users/<username>
-
 .. _user_schema:
 
 User Schema
@@ -50,8 +42,18 @@ In JSON, a User object has the following properties:
       - Read-only
       - Time the user registered at.
 
-Endpoints
----------
+.. _user_info_api:
+
+User Info API
+-------------
+
+The User Info API allows managing users and their permissions.
+
+Sachet implements the following endpoints for this API::
+
+    GET /users/<username>
+    PATCH /users/<username>
+    PUT /users/<username>
 
 GET
 ^^^
@@ -115,8 +117,10 @@ For example:
 
 Only :ref:`administrators<permissions_table>` can request this method.
 
-User List API
--------------
+.. _user_list_api:
+
+List API
+--------
 
 There is also a User List API::
 
@@ -133,5 +137,5 @@ GET
 POST
 ^^^^
 
-``POST /users/`` creates a new user.
+``POST /users`` creates a new user.
 The request body must conform to the :ref:`User schema<user_schema>`.