RestAPI and Web Server

Suggest edits
Documentation > Developers

Contents

Web Server đź”—

Warning: The REST API of OpenMOLE is still experimental, it might be subject to some backward incompatible changes in the future.

OpenMOLE ships with a web server providing a REST API to start workflows, manage their execution and retrieve their output data. To start the OpenMOLE REST API, run the command: "openmole --rest --port 8843" from the console. If you need to launch it automatically in a deamon for instance you should also you the --password-file argument to provide the password for encryption of the preferences.

The web server can be accessed at the URL https://localhost:8443. Replace localhost with the remote machine's hostname or IP address if the web server is not running on your local system.

API Reference đź”—

The API of the web server uses exclusively the POST method:
  • token - return a temporary token in order to use the web service. It has the following parameters:
    • password - the password of the server
    It return a structure containing:
    • token - the token
    • duration - the duration of the token in milliseconds
  • start - start a mole execution. It has the following parameters:
    • token - the authentication token
    • workDirectory - a tar.gz archive containing the workDirectory for the script
    • ,
    • script - the path (relative to the workDirectory) of script to execute, the last line should be a puzzle
    When successful, it return a structure containing:
    • id - the id of the execution
    When something has failed, it returns a structure containing:
    • message - the error message
    • stackTrace - optionally a stack trace if the error has been caused by an exception
  • state - return the state of a mole execution. It has the following parameters:
    • token - the authentication token
    • id - the id of the mole execution
    When successful, it returns a structure the state:
    • state - the state of the execution, it can be running, finished or failed
    When running the other fields are:
    • ready, running, completed - the number of jobs in each of these states in the execution
    • environments - that contains the state for each execution environment on the execution. This is a JSON structure containing, the name of the environment if it has been set (name), the number of jobs in submitted (submitted), running (running), done (done) and failed (failed) state, a list of errors that happened since the last state query (errors) with the message (message), the stack (stackTrace) and the error level (level).
    When failed the other field is:
    • error: a JSON structure containing the message (message) and the stack (stackTrace)
  • output - returns the output of a mole execution as a string. It has the following parameters:
    • token - the authentication token
    • id - the id of the mole execution
  • download - download a file or a directory from the server. It returns the gunziped content of the file or a tar.gz archive of the directory. It has the following parameters:
    • token - the authentication token
    • id - the id of the mole execution
    • path
    • - the path of the file to download}
  • remove - cancel and remove an execution from the server. It has the following parameters:
    • token - the authentication token
    • id - the id of the mole execution
  • list - list execution ids on the server. It has the following parameters:
    • token - the authentication token