### API ### davos provides an HTTP API that exposes Schedules and Hosts so they can be managed outside the scope of the web application. This API is also used by the web application's AJAX calls. .. warning:: This API is completely unauthenticated, so anyone on your network can use this ********* /schedule ********* POST ---- Creates a single Schedule. .. code-block:: text POST /api/v2/schedule HTTP 1.0 Host: localhost:8080 Content-Type: application/json Accept: application/json { "name": String, "interval": Integer, "host": Integer, "hostDirectory": String, "localDirectory": String, "transferType": String [ FILE | RECURSIVE ], "automatic": Boolean, "moveFileTo": String, "filtersMandatory": Boolean, "invertFilters": Boolean, "deleteHostFile": Boolean, "filters": [ { "value": String } ], "notifications": { "pushbullet": [ { "apiKey": String } ], "sns": [ { "topicArn": String, "region": String, "accessKey": String, "secretAccessKey": String } ] }, "apis": [ { "url": String, "method": String [ POST | GET | PUT | DELETE ], "contentType": String, "body": String } ] } For more information regarding what each field represents, see the :doc:`../guides/gettingstarted/schedules` documentation in :doc:`../guides/gettingstarted/index`. Response ======== See: :ref:`Schedule Response Syntax `. ************** /schedule/{id} ************** GET --- Retrieves a single Schedule based on the supplied ``{id}``. .. code-block:: text GET /api/v2/schedule/{id} HTTP 1.0 Host: localhost:8080 Accept: application/json Response ======== See: :ref:`Schedule Response Syntax `. PUT --- Updates a single Schedule based on the given ``{id}``. All fields must be supplied, even if only a subset is being updated. Use a GET to first obtain the most up-to-date payload before performing a PUT. .. code-block:: text PUT /api/v2/schedule/{id} HTTP 1.0 Host: localhost:8080 Content-Type: application/json Accept: application/json { "name": String, "interval": Integer, "host": Integer, "hostDirectory": String, "localDirectory": String, "transferType": String [ FILE | RECURSIVE ], "automatic": Boolean, "moveFileTo": String, "filtersMandatory": Boolean, "invertFilters": Boolean, "deleteHostFile": Boolean, "filters": [ { "id": Integer, "value": String } ], "notifications": { "pushbullet": [ { "id": Integer, "apiKey": String } ], "sns": [ { "id": Integer, "topicArn": String, "region": String, "accessKey": String, "secretAccessKey": String } ] }, "apis": [ { "url": String, "method": String [ POST | GET | PUT | DELETE ], "contentType": String, "body": String } ] } .. note:: If you are updating a listed object, you must provide the object's ``id``. If you do not, the API will remove the old reference and create a new one. To add a new item to the list, provide the new item (without an ``id``) alongside the existing one. Response ======== See: :ref:`Schedule Response Syntax `. DELETE ------ Deletes a single Schedule with the given ``{id}``. .. code-block:: text DELETE /api/v2/schedule/{id} HTTP 1.0 Host: localhost:8080 Accept: application/json Response ======== .. code-block:: javascript { "status": String [ OK | Failed ], "body": String } *************************** /schedule/{id}/scannedFiles *************************** DELETE ------ Clears all items in the given Schedule's ``lastScannedFiles``. .. code-block:: text DELETE /api/v2/schedule/{id}/scannedFiles HTTP 1.0 Host: localhost:8080 Accept: application/json Response ======== .. code-block:: javascript { "status": String [ OK | Failed ], "body": String } ********************** /schedule/{id}/execute ********************** POST ---- Starts/Stops an existing Schedule. .. code-block:: text POST /api/v2/schedule/{id}/execute Host: localhost:8080 Content-Type: application/json Accept: application/json { "command": String [ START | STOP ] } Response ======== .. code-block:: javascript { "status": String [ OK | Failed ], "body": String } ***** /host ***** POST ---- Creates a new Host. .. code-block:: text POST /api/v2/host Host: localhost:8080 Content-Type: application/json Accept: application/json { "name": String, "address": String, "port": Integer, "protocol": String [ FTP | FTPS | SFTP ], "username": String, "password": String, "identityFile": String, "identityFileEnabled": Boolean } .. note:: If ``identityFileEnabled`` is set to TRUE, you must also provide ``identityFile``, otherwise provide ``password``. ********** /host/{id} ********** GET --- Retrieves a single Host based on the given ``{id}``. .. code-block:: text GET /api/v2/host/{id} Host: localhost:8080 Accept: application/json Response ======== See: :ref:`Host Response Syntax `. PUT --- Updates a Host with the given ``{id}``. .. code-block:: text POST /api/v2/host/{id} Host: localhost:8080 Content-Type: application/json Accept: application/json { "name": String, "address": String, "port": Integer, "protocol": String [ FTP | FTPS | SFTP ], "username": String, "password": String, "identityFile": String, "identityFileEnabled": Boolean } .. note:: If ``identityFileEnabled`` is set to TRUE, you must also provide ``identityFile``, otherwise provide ``password``. Response ======== See: :ref:`Host Response Syntax `. DELETE ------ Deletes a single Host with the given ``{id}``. .. code-block:: text DELETE /api/v2/host/{id} HTTP 1.0 Host: localhost:8080 Accept: application/json Response ======== .. code-block:: javascript { "status": String [ OK | Failure ], "body": String } .. warning:: If the Host you are attempting to delete is being used by an active Schedule, the DELETE call will fail. *************** /testConnection *************** POST ---- Allows you to assert whether or not the provided payload contains valid Host information. .. code-block:: text POST /api/v2/testConnection Host: localhost:8080 Content-Type: application/json { "id": Integer, "name": String, "address": String, "port": Integer, "protocol": String [ FTP | FTPS | SFTP ], "username": String, "password": String, "identityFile": String, "identityFileEnabled": Boolean } Response ======== .. code-block:: javascript { "status": String [ OK | Failed ], "body": String } ************* /settings/log ************* POST ---- Changes the logging level of the application's core code. Unlike other POST calls, there is no payload body. The level is passed in as a request parameter. level The level to change the logging to. Available options are DEBUG, INFO, WARN, ERROR, FATAL .. code-block:: text POST /api/v2/settings/log?level={LEVEL} Host: localhost:8080 Accept: application/json Response ======== .. code-block:: javascript { "status": String [ OK | Failed ], "body": String } ********* Responses ********* .. _schedule-response: Schedule Response Syntax ------------------------ .. code-block:: javascript { "status": String [ OK ], "body": { "id": Integer, "name": String, "interval": Integer, "host": Integer, "hostDirectory": String, "localDirectory": String, "transferType": String [ FILE | RECURSIVE ], "automatic": Boolean, "moveFileTo": String, "running": Boolean, "filtersMandatory": Boolean, "invertFilters": Boolean, "lastRunTime": String, "deleteHostFile": Boolean, "lastScannedFiles": [ String ], "filters": [ { "id": Integer, "value": String } ], "notifications": { "pushbullet": [ { "id": Integer, "apiKey": String } ], "sns": [ { "id": Integer, "topicArn": String, "region": String, "accessKey": String, "secretAccessKey": String } ] }, "transfers": [ { "fileName": String, "fileSize": Integer, "directory": Boolean, "progress": { "percentageComplete": Double, "transferSpeed": Double }, "status": String [ DOWNLOADING | SKIPPED | PENDING | FINISHED ] } ], "apis": [ { "id": Integer, "url": String, "method": String [ POST | GET | PUT | DELETE ], "contentType": String, "body": String } ] } } .. note:: ``running``, ``lastScannedFiles``, ``lastRunTime`` and ``transfers`` are immutable metadata fields and can't be used in PUT or POST requests. If supplied, they will be ignored. .. host References the ``id`` of the linked host. running Descibes whether or not the Schedule is running. lastRunTime The time recorded when the Schedule last *finished* running. lastScannedFiles A list of Strings that represent the files/folders found in the last run of the schedule. transfers A list of transfer objects that describe all files being actioned. This list will only be populated when the Schedule is running and is actively downloading. .. _host-response: Host Response Syntax -------------------- Success ======= .. code-block:: javascript { "status": String [ OK ], "body": { "id": Integer, "name": String, "address": String, "port": Integer, "protocol": String [ FTP | FTPS | SFTP ], "username": String, "password": String, "identityFile": String, "identityFileEnabled": Boolean } } Failure ======= .. code-block:: javascript { "status": String [ Failed ], "body": String }