Filesystems API
===============

==================
Filesystem Methods
==================

Filesystems are where files are uploaded and accessed by compute jobs.


.. http:get:: /filesystems

    Lists all available filesystems.

    :reqheader Authorization: API key or Bearer token for user authentication.
    :status 200: Success. Returns the initialization information if it's an initialization request.
    :status 500: Unknown error.

    
    **Response Syntax**:

    .. sourcecode:: json

     [
       {
         "filesystem_id": "string",
         "filesystem_name": "string"
       }
     ]

    :raises: May raise exceptions related to database operations or service availability.


.. http:post:: /filesystems

    Creates a new filesystem.

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. Returns the initialization information if it's an initialization request.
    :status 400: Bad request.
    :status 409: Filesystem already exists and was not created.
    :status 500: Unknown error.

    
    **Request Syntax**:

    .. sourcecode:: json

     {
       "filesystem_name": "string"
     }

    **Response Syntax**:

    .. sourcecode:: json

     {
       "filesystem_id": "string",
       "filesystem_name": "string"
     }

    :raises: May raise exceptions related to database operations or service availability.


.. http:delete:: /filesystems/<filesystem_id>

    Deletes a filesystem and all its contents.


.. http:post:: /filesystems/<filesystem_id>/share

    Shares the Filesystem with the specified user.


.. http:get:: /filesystems/<filesystem_id>/list/<path:directory>

    Lists all files and sub-directories within the specified directory.


.. http:post:: /filesystems/<filesystem_id>/mkdir/<path:directory>

    Makes a new directory at the specified path.


.. http:get:: /filesystems/<filesystem_id>/files/<path:file_path>

    Downloads a chunk of a file.

    Download a chunk of a file.

    :reqheader Authorization: API key or Bearer token for user authentication
    :reqheader Content-Range: Byte range for this file, in the format <START>-<END>
    :status 200: Success.
    :status 403: Requested file path forbidden.
    :status 400: Invalid Content-Range header.
    :status 500: Unknown error occurred during processing.

    Pass the query string param ?init=true to obtain the file size and a download_id

    :raises: May raise exceptions related to database operations or service availability.


.. http:post:: /filesystems/<filesystem_id>/files/<path:file_path>

    Initialize or complete a multipart upload. Initializations include the size in the request body. Completions include the upload ID and a boolean true/false string in the body.

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. Returns the initialization information if it's an initialization request.
    :status 403: Requested file path forbidden.
    :status 400: Invalid request body.
    :status 500: Unknown error occurred during processing.

    **Request Syntax (Initialize)**:

    .. sourcecode:: json

     {
       "size": 123
     }

    **Request Syntax (Complete)**:

    .. sourcecode:: json

     {
       "complete": true
       "uploadId": "string"
    }

    **Response Syntax (Initialize)**:

    .. sourcecode:: json

     {
       "uploadId": "string"
     }

    :raises: May raise exceptions related to database operations or service availability.


.. http:put:: /filesystems/<filesystem_id>/files/<path:file_path>

    Upload a chunk of a file.

    :reqheader Authorization: API key or Bearer token for user authentication
    :reqheader Content-Range: Upload ID and byte range for this file, in the format [<UPLOAD_ID>]:<START>-<END>
    :status 200: Success.
    :status 403: Requested file path forbidden.
    :status 400: Invalid Content-Range header.
    :status 401: Content-Range doesn't match length of body.
    :status 500: Unknown error occurred during processing.

    :raises: May raise exceptions related to database operations or service availability.


.. http:delete:: /filesystems/<filesystem_id>/files/<path:file_path>

    Deletes the specified file from the Filesystem.