Rest API

Suggest edits
Documentation > Developers

Contents

REST API đź”—

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 8080" 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 http://localhost:8080. 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 exposes the following routes to submit and manage executions:
  • POST /job - start a mole execution. It has the following parameters:
    • 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
  • GET /job/:id/state - return the state of a mole execution. It has the following parameters:
    • 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)
  • GET /job/:id/output - returns the output of a mole execution as a string. It has the following parameters:
    • id - the id of the mole execution
  • GET /job/:id/workDirectory/:file - 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:
    • id - the id of the mole execution
    • path
    • - the path of the file to download}
  • DELETE /job/:id - cancel and remove an execution from the server. It has the following parameters:
    • id - the id of the mole execution
  • GET /job/ - list execution ids on the server.
The API of exposes the following routes to submit and manage the plugins:
  • GET /plugin/ - list all user plugins loaded in OpenMOLE It returns a list containing the name of the plugins an a boolean set to true if the plugin is properly loaded.
  • POST /plugin - load one or several plugins in OpenMOLE. It has the following parameter:
    • file - an OpenMOLE plugin file. Repeat this parameter to submit several plugins at once.
    When some errors occurs while loading some plugins it return a list containing the name of the plugin an the error that occurred while loading this plugins.
  • DELETE /plugin - unload (and remove) one or several plugins in OpenMOLE. Depending plugin are unloaded as well. It has the following parameter:
    • name - the name of an OpenMOLE plugin. Repeat this parameter to submit several plugins at once.
    It return a list with the name of the plugins which have ben unloaded.

Examples đź”—

Launch the REST server:
[reuillon:~] $ openmole --rest
Enter your OpenMOLE password (for preferences encryption): *******
Jan 08, 2020 3:34:41 PM org.openmole.rest.server.RESTServer server$lzycompute
INFO: binding HTTP REST API to port 8080
Prepare the work directory:
[reuillon:~] $ cd /tmp/pi/
[reuillon:/tmp/pi] $ ls
Pi.oms
[reuillon:/tmp/pi] $ cat Pi.oms
// Define the variables that are transmitted between the tasks
val seed = Val[Long]
val pi = Val[Double]

val piAvg = Val[Double]
val piMed = Val[Double]
val testFile = Val[File]

// Define the model task that computes an estimation of pi
val model =
  ScalaTask("""
    |val random = newRNG(seed)
    |val points = 10000
    |val inside =
    |  for {
    |    i <- (0 until points).toIterator
    |    x = random.nextDouble()
    |    y = random.nextDouble()
    |  } yield { (x * x) + (y * y) }
    |val pi = (inside.count(_ < 1).toDouble / points) * 4
    |""".stripMargin) set (
      inputs += seed,
      outputs += pi
    )


Replication(
  evaluation = model,
  seed = seed,
  replications = 100,
  aggregation = Seq(pi aggregate average as piAvg, pi aggregate median as piMed)
) hook display

[reuillon:/tmp/pi] $ tar -cvzf pi.tgz *
Submit the job:
[reuillon:/tmp/pi] 1m59s $ curl -X POST -F 'script=Pi.oms' -F 'workDirectory=@/tmp/pi.tgz' http://localhost:8080/job
{
  "id" : "160ba693-199c-48e8-9ee1-6a1f9ac66e62"
}[reuillon:/tmp/pi] 3m12s $ curl -X GET http://localhost:8080/job/160ba693-199c-48e8-9ee1-6a1f9ac66e62/state
{
  "state" : "finished"
}[reuillon:/tmp/pi] 4m5s $ curl -X GET http://localhost:8080/job/160ba693-199c-48e8-9ee1-6a1f9ac66e62/output
piAvg,piMed
3.1415440000000006,3.1416
List the plugins:
[reuillon:~/myopenmoleplugin] $ curl -X GET http://localhost:8080/plugin/
[ {
  "name" : "h24_2.12-1.0-SNAPSHOT.jar",
  "active" : true
}, {
  "name" : "zombies-bundle_2.12-0.1.0-SNAPSHOT.jar",
  "active" : true
} ]
Load a plugin:
[reuillon:~/myopenmoleplugin] $ curl -X POST http://localhost:8080/plugin -F 'file=@./target/scala-2.12/myopenmoleplugin_2.12-1.0.jar'
Unload the plugin:
[reuillon:~/myopenmoleplugin] $ curl -X DELETE http://localhost:8080/plugin?name=myopenmoleplugin_2.12-1.0.jar
[ "myopenmoleplugin_2.12-1.0.jar" ]