Rest API

Suggest edits
Documentation > Developers

Content:



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 give 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 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 the script to execute, the last line should be a puzzle
    When successful, it returns 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 representing 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
  • PROPFIND /job/:id/workDirectory/:file - get info of a file or a directory from the server. It has the following parameters:
    • id - the id of the mole execution
    • path - the path of the file to download
    • last - this parameter is optional - an integer to list only the last n files.
    When successful, it returns a listing of the directory, that look like this:
    {
      "entries" : [ {
        "name" : "Pi.oms",
        "size" : 909,
        "modified" : 1584980668517,
        "type" : "file"
      } ],
      "modified" : 1584980668517,
      "type" : "directory"
    }
    The fields contains the following info:
    • name - the name of the file
    • type - the type of the file. It can be (directory or file)
    • modified - the date of the last modification of this file
    • size - mentioned only for the entry of type "file". It contains the size of the file.
  • 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 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 mySeed = Val[Long]
val pi = Val[Double]

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

// 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 = mySeed,
  sample = 100,
  aggregation = Seq(pi aggregate average as piAvg, pi aggregate median as piMed)
) hook display hook (workDirectory / "result.json", format = JSONOutputFormat())

[reuillon:/tmp/pi] $ tar -cvzf pi.tgz *

Submit the job 🔗

[reuillon:/tmp/pi] $ 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] $ curl -X GET http://localhost:8080/job/160ba693-199c-48e8-9ee1-6a1f9ac66e62/state
{
  "state" : "finished"
}[reuillon:/tmp/pi] $ curl -X GET http://localhost:8080/job/160ba693-199c-48e8-9ee1-6a1f9ac66e62/output
piAvg,piMed
3.1415440000000006,3.1416
[reuillon:/tmp/pi] $ curl -X PROPFIND http://localhost:8080/job/160ba693-199c-48e8-9ee1-6a1f9ac66e62/workDirectory/
{
  "entries" : [ {
    "name" : "result.json",
    "size" : 43,
    "modified" : 1584981433544,
    "type" : "file"
  }, {
    "name" : "Pi.oms",
    "size" : 869,
    "modified" : 1584981429072,
    "type" : "file"
  } ],
  "modified" : 1584981433540,
  "type" : "directory"
}[reuillon:/tmp/pi] $ curl -X GET http://localhost:8080/job/160ba693-199c-48e8-9ee1-6a1f9ac66e62/workDirectory/result.json -O -J && gunzip result.json.gz && cat result.json
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                               Dload  Upload   Total   Spent    Left  Speed
100    50    0    50    0     0   4166      0 --:--:-- --:--:-- --:--:--  4166
curl: Saved to filename 'result.json.gz'
{"piAvg":3.1415440000000006,"piMed":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" ]