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...