Data Upload
===========

.. code-block:: http

    /api/repositories/{repository}/entities/upload

.. csv-table::
    :header: Parameter, Type, Purpose
    :widths: 20, 20, 60
    :stub-columns: 1

    repository, string, The name of the :doc:`repository` to access

Post
~~~~

.. http:post:: /api/repositories/(string:repository)/entities/upload
    :synopsis: Upload a data file to the server file system so that it can be used to create an entity

.. code-block:: http

    POST /api/repositories/jupiter/entities/upload HTTP/1.1

The message body takes a ``file`` as input. The encoding should be set to ``enctype='multipart/form-data'``.

Only one file can be uploaded at a time.

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, File uploaded to the server
    400, Invalid data passed with request
    500, Server error

A successful response contains the virtual path to the file that is uploaded.

If the server filesystem contains another file with the same name, the file will be renamed to an unique name.

This API should be used for uploading data from client file system before creating an :doc:`entity`. 

The files will be created under `import` directory in the repository environment location.
A separate directory will be created for each user under `_upload` directory within `import` directory.

A sample response would be as follows:

.. code-block:: json

    {
        "path": "/vupload/sample.txt"
    }

``/vupload`` represents the directory `import/_upload/{user}` within the repository environment, where ``user`` is the username of the user uploading the data.

It is advisable to use traditional methods of uploading like `ftp` or `sftp` if you have to trasfer huge amount of data (over 200 MB). 
These uploads could be quite slow if you are using `standalone` Node server. If you are using `integrated` Node server, the data is transfered much faster.