Rest API

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 evaluate average as piAvg, pi evaluate 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" ]