Launcher API Documentation

Introduction

This document will cover the expected RESTful API for launching a ParaViewWeb process. For details on our launcher implementation, see the Python Launcher guide. Also, see the Launching Examples guide for descriptions of some of the deployment configurations possible with our provided launcher.

Role of the launcher

The launcher has a well-defined set of responsibilities:

  1. listen for incoming client requests for new visualization process,
  2. find an available “resource” from list it maintains (a “resource” is simply a [host, port] combination),
  3. launch the requested command-line,
  4. wait for that command-line process to be ready and when it is ready, note the session-id, host, and port in the mapping file,
  5. and finally, respond to the client with the proper information (including at least the sessionURL where the client can reach the running visualization process)

Process launcher RESTful API

VTKWeb/ParaViewWeb come with a JavaScript library, which allows the user to trigger a new process on the server side in a configurable manner.

The following code example illustrates what can be done on the client side, and we will explain what should be expected by the server.

import SmartConnect from 'paraviewweb/src/IO/WebSocket/SmartConnect';

const config = {
   'sessionManagerURL' : 'http://localhost:8080/paraview',
   'application': 'loader',
   'key1': 'value1',
   'key2': 'value2',
   ...
   'keyN': 'valueN'
}

const smartConnect = new SmartConnect(config);
smartConnect.onConnectionReady((connection) => { /* start app */});
smartConnect.connect();

The preceeding client code will trigger a POST request on http://localhost:8080/paraview with the given config object as payload. In response, the server will first start the application specified in the config application value, and then it should return the initial config object with additional keys such as:

  • sessionURL: contains the WebSocket URL where the client should connect to in order
    to connect to the newly started process. (ws://localhost:8080/proxy?id=2354623546)
  • secret: contains the password that should be used to authenticate the client on the WebSocket connection.
  • id: contains the session ID that can be used to query the launcher in order to retrieve the full connection information.

In the case of a two-step connection, a client may want to trigger a GET request on http://localhost:8080/paraview/${sessionID} in order to get the full config object illustrated earlier.

The launcher should now also be capable of stopping a running process by triggering a DELETE request on http://localhost:8080/paraview/${sessionID}. This will return the same config object illustrated earlier.

RESTful Cheat sheet

URL HTTP Method Upload content Download content
http://host:port/endpoint POST { sessionManagerURL: ‘http://host:port/endpoint', application: ‘value’} { sessionManagerURL: ‘http://host:port/endpoint', application: ‘value’, id: ‘234523’, sessionURL: ‘ws://host:port/proxy?id=234523’}
http://host:port/endpoint/234523 GET - { sessionManagerURL: ‘http://host:port/endpoint', application: ‘value’}
http://host:port/endpoint/234523 DELETE - { sessionManagerURL: ‘http://host:port/endpoint', application: ‘value’}

Then, once the service receives a POST request, it will trigger a new command line, which will have its output redirected to /tmp/pw-log/${session_id}.log where the ${session_id} will be a unique generated string that will ID the given process.

For example, if the client sends the given JSON payload

{
'sessionManagerURL': 'http://localhost:8080/paraview',
'application': 'launcher',
'node': 1024,
'secret': 'katglrt54#%dfg',
'user': 'sebastien.jourdain',
'password': 'ousdfbdxldfgh',
'app': 'Visualizer'
}

The server should first run the command line associated with the application launcher (see the Python Launcher guide for information about how the application commands lines are configured).

Once the command line is running, the server should respond something like:

{
'sessionManagerURL': 'http://localhost:8080/paraview',
'application': 'launcher',
'node': 1024,
'secret': 'katglrt54#%dfg',
'user': 'sebastien.jourdain',
'password': 'ousdfbdxldfgh',
'app': 'Visualizer',
'id': '2345634574567',
'sessionURL': 'ws://localhost:8080/proxy/2345634574567'
}