.. _folder-create:

Create a new Folder
===================

Can create top level and sub level folders. The folder will be created on a given target node. Node IDs can be found in the web portal.


.. code-block:: python
   :caption: Endpoint

    POST https://api.cloudplan.net/api/folder/create


Request Parameters
------------------
    
.. code-block:: python
    :caption: Possible request parameters

    {
        "node_id": "",
        "folder_name": "",
        "parent_id": ""
    }



.. admonition:: node_id | *(string)*
    :class: admonition-property

    *This parameter is optional when parent_id is set (i.e. a sub level is created)*

    Create the folder on this specific node. If a *parent_id* is given and *node_id* is left empty a suitable node will be selected automatically with priority on the *private cloud nodes*.

    If a *parent_id* is given it can be the id of any node that synchronizes the parent folder. 


.. admonition:: folder_name | *(string)*
    :class: admonition-property

    Name of the new folder


.. admonition:: parent_id | *(optional)* *(string)*
    :class: admonition-property

    If left empty a top-level folder will be created on the given node. Otherwise the new folder will be created as sub-level folder of this.


Reply Parameters
----------------
    
.. code-block:: python
    :caption: JSON Reply
    
    {
        "folder_id": ""
    }

.. admonition:: folder_id | *(string)*
    :class: admonition-property

    The id of the folder that was created.


.. warning:: 

    If the api returns **timeout_db** or a similar error, **the target node may still have created the folder successfully**. It is possible that the synchronization processes between node and server backend was too slow at that moment. Check the content on the nodes drive to be certain. 


Example
-------

This request creates a sub folder in a given parent folder with automatic storage node selection.

.. code-block:: JSON
    :caption: Example request

    {
        "parent_id": "6319C982C7C0D952BFAA7347D212E57D",
        "folder_name": "testapi1"
    }
    

.. code-block:: JSON
    :caption: Reply for the example request
    
    {
        "result": true,
        "folder_id": "696E0525F62C01AB095421152ECAACC8"
    }