WIP - docs/files.rst: added content

2023-05-20 22:31:42 -04:00 · 2023-05-20 22:31:42 -04:00 · 1f7ade3c1f
commit 1f7ade3c1f
parent 2914ff7856
1 changed files with 146 additions and 0 deletions
--- a/docs/files.rst
+++ b/docs/files.rst
@ -1,2 +1,148 @@
 Files API
 =========
+
+.. _files_schema:
+
+File Schema
+-----------
+
+In JSON, a file share has the following properties::
+
+    {
+        "file_name": "file.txt",
+        "initialized": true,
+        "locked": false,
+        "owner_name": "user",
+        "share_id": "9ae90f06-a751-409c-a9fe-8277575b9914"
+    }
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 25 25 50
+
+    * - Property
+      - Type
+      - Limits
+      - Description
+    * - ``file_name``
+      - String
+      -
+      - The file's name (with extension).
+    * - ``initialized``
+      - Boolean
+      - Read-only
+      - Shows if content exists for this share.
+    * - ``locked``
+      - Boolean
+      - Read-only
+      - Shows if share is locked.
+    * - ``owner_name``
+      - string
+      -
+      - Username of the owner.
+    * - ``share_id``
+      - string
+      - Read-only
+      - UUID that uniquely identifies this share.
+
+Metadata API
+------------
+
+The File Metadata API allows managing file shares' metadata.
+
+Sachet implements the following endpoints for this API::
+
+    GET /files/<file_uuid>
+    PATCH /files/<file_uuid>
+    PUT /files/<file_uuid>
+
+GET
+^^^
+Requesting ``GET /files/<file_uuid>`` returns a JSON object conforming to the :ref:`File schema<files_schema>`.
+This contains the information about the share with the specified UUID.
+
+An example response:
+
+.. code-block:: json
+
+    {
+        "file_name": "file.txt",
+        "initialized": true,
+        "locked": false,
+        "owner_name": "user",
+        "share_id": "9ae90f06-a751-409c-a9fe-8277575b9914"
+    }
+
+This method requires the :ref:`read<permissions_table>` permission.
+
+PATCH
+^^^^^
+
+Requesting ``PATCH /files/<file_uuid>`` allows modifying some or all fields of the share's metadata.
+The request body is JSON conforming to the :ref:`File schema<files_schema>`.
+Properties may be left out: they won't be modified.
+
+For example, to modify a share's filename:
+
+.. code-block:: json
+
+    {
+        "file_name": "foobar.mp3"
+    }
+
+This method requires the :ref:`modify<permissions_table>` permission.
+
+PUT
+^^^
+
+Requesting ``PUT /files/<file_uuid>`` completely replaces a share's metadata.
+The request body is JSON conforming to the :ref:`File schema<files_schema>`.
+No property may be left out.
+
+For example:
+
+.. code-block:: json
+
+    {
+        "file_name": "foobar.mp4",
+        "owner_name": "user"
+    }
+
+.. note::
+
+    The permissions from the schema that are missing here are read-only.
+
+Content API
+-----------
+
+The File Content API allows managing file shares' contents.
+
+Sachet implements the following endpoints for this API::
+
+    POST /files/<file_uuid>/content
+    PUT /files/<file_uuid>/content
+    GET /files/<file_uuid>/content
+
+.. _files_chunked_upload :
+
+Chunked upload protocol
+^^^^^^^^^^^^^^^^^^^^^^^
+To allow for uploading large files reliably, Sachet requires that you upload files in chunks.
+
+Partial uploads do not affect the state of the share;
+a new file exists only once all chunks are uploaded.
+
+Every chunk has the following schema:
+
+.. _files_chunk_schema :
+
+.. code-block:: json
+
+{
+    "dztotalchunks": 3,
+    "dzchunkindex": 2,
+    "dzuuid": "unique_id"
+}
+
+..
+    TODO...