In the case of errors, the ``data`` field contains an object, containing
a field named ``extra`` with an extended explanation of the error.

The API calls have the form ``/api//resource?cmd=&``
where ```` is the API version number, can be just ``1``, ``1.0`` or
``1.0.0``. At this moment, it is the only version available, but version
``1`` will indicate the highest API version available of the ``1.x.x``
range.

Available Commands
~~~~~~~~~~~~~~~~~~

Directory Operations
....................

list
,,,,

List the contents of a directory. Does not need to be specified::

GET /api/1/?cmd=list
GET /api/1/

The response data field contains the following fields:

name:
Name of the directory
files:
List of file objects
directories:
List of directories
links:
List of possible operations

archive
,,,,,,,

Download a compressed archive with the contents of the directory::

GET /api/1/?cmd=archive&format=

mkdir
,,,,,

Create new directory::

POST /api/1/?cmd=mkdir

If successful, the response will be ``204 No content``

upload
,,,,,,

Upload file(s) to directory::

POST /api/1/?cmd=upload

The files can be uploaded by simply sending the file in the body of the
request, or sending several files in a multipart message.

If successful, the response will be ``204 No content``

delete
,,,,,,

Remove the directory::

DELETE /api/1/

This command removes the entire tree without asking for confirmation. Use
with caution.

If successful, the response will be ``204 No content``

File Operations
...............

download
,,,,,,,,

Download a file::

GET /
GET /api/1/
GET /api/1/?cmd=download

It is not necessary to specify the command or the API/version prefix.
The mime type of the file is guessed based on the name using the Python
Standard Library ``mimetypes`` module.

info
,,,,

Miscellaneous information about a file::

GET /api//path?cmd=info

Upon success, the response ``data`` field will contain a JSON object with
the following files:

name:
The name of the file.
size:
The size in bytes, as a number.
human_size:
The size in a string, expressed in the easiest to read unit.
path:
Path from the top directory.
checksum:
The sha256 checksum.
atime:
Last access time, as a string in ISO format.
mtime:
Last modification time, as a string in ISO format.
ctime:
Creatrion time, as a string in ISO format.

Example::

GET /api/1/opt/jdk1.8.0_51/COPYRIGHT?cmd=info
{
"rc": 200,
"msg": "OK",
"api_version": "1.0.0",
"data": {
"name": "COPYRIGHT",
"size": 3244,
"human_size": "3.17 KB",
"path": "/opt/jdk1.8.0_51",
"checksum": "89471aea3957922df21c7088d2687c4e43f5ff14e635e7d971083dde540b45e3",
"atime": "2019-11-15T23:33:56.430384+00:00",
"mtime": "2015-06-09T02:37:58+00:00",
"ctime": "2015-07-20T18:17:40.394882+00:00"
}
}

compress
,,,,,,,,

Compress and download a single file::

GET /api/1/?cmd=compress&format=

checksum
,,,,,,,,

Compute, and optionally check, the SHA256 checksum of a file::

GET /api/1/?cmd=checksum
GET /api/1/?cmd=checksum&match=

If no arguments are given the checksum of the file is computed and
returned in the ``data`` field of the JSON response, which has the
following fields:

filename:
The base filename for which the checksum was computed.
checksum:
The SHA256 digest as a lower case hexadecimal number.

If the ``match`` argument was used, it is used to compare it to the
computed checksum, and the following field is returned in addition to
the above:

match:
A boolean indicating whether the checksums match.

Example::

GET /api/1/opt/jdk1.8.0_51/COPYRIGHT?cmd=checksum&match=89471aea3957922df21c7088d2687c4e43f5ff14e635e7d971083dde540b45e3
{
"rc": 200,
"msg": "OK",
"api_version": "1.0.0",
"data": {
"checksum": "89471aea3957922df21c7088d2687c4e43f5ff14e635e7d971083dde540b45e3",
"filename": "COPYRIGHT",
"match": true
}
}

copy
,,,,

Copy a file::

POST /api/1/?cmd=copy&dest=

If successful, the response will be ``204 No content``

move
,,,,

Move or rename a file::

POST /api/1/?cmd=move&dest=

If successful, the response will be ``204 No content``

.. _configuration:

Configuration
-------------

It is possible to manage permissions for each of the operations
supported by the API on a global or per directory or file basis. These
permissions should be specified in a Windows .ini configuration file.

Each section in the .ini file has a variable called 'allow' whose contents
are the names of the individual API commands, separated by commas, or
the special words ``all`` or ``none`` which grant permission for all
actions or deny them respectively.

There is a ``DEFAULT`` section that contains the global commands that
are allowed in all the directories not specified and sections for each
directory or file for which we want different permissions. For example,
consider the following ``.ini`` file::

[DEFAULT]
allow = list, download, mkdir, upload, info, checksum
[/dir_004]
allow = ${DEFAULT:allow}, compress, archive
[/dir_003]
allow = ${/dir_004:allow}
[/dir_003/dir_025]
allow = all
[/dir_003/dir_024/dir_026]
allow = none

The default section applies globally and provides a restricted, but
reasonable set of commands. The sections ``[/dir_004]`` and ``[/dir_003]``
specify an augmented set of permissions, based on those of the default
section. This is important: once we have a section for a directory, the
global permissions no longer apply and we must explicitly allow all the
command that we want. In this example we are *inheriting*
the permissions using the *Extended Interpolation* notation provided by
the Python ``configparser`` module.

All operations will be permitted for the directory ``/dir_003/dir_025``
and everything under it, including copying and deletion, and on
directory ``/dir_003/dir_024/dir_026`` no operations whatsoever are
permitted and we won't even be able to list its contents.

The configuration file is specified using the ``--config cfg`` command
line option, e.g.::

$ httpuploader --config config.ini --rootdir $HOME

If no configuration file is specified, the default permissions settings
will be::

[DEFAULT]
allow = list, download, mkdir, upload