API.md

Scripting API

This document contains the current API for the scripts of PilotSSH. It defines a simple JSON interface that will not depend on the scripting language. The commands presented here all use Bash, but Perl, Python, Ruby, anything you can think of should be used.

Bootstrap

The first script called by PilotSSH is .pilotssh/index. This script follows the same API as other scripts, and is commonly used to find other commands.

API responses

The application calls scripts, and will parse the JSON output to generate its user interface. Here is the format of the result:

{
  "version" : 1,
  "title"   : "Index",
  "type"    : "commands",
  "status"  : "",
  "message" : "",
  "values"  : [
    {
      "name" : "logs",
      "value" : "",
      "command" : ".pilotssh/logs.sh"
    }
  ],
  "text": ""
}

• version: set to 1 for now. It must be present in every response
• title: defines the page's title in the application, or the alertbox's title (for status messages). It must be present in every response
• type: defines the type of answer, and the way the application will handle it. It can take three values: commands, status and text. It must be present in every response
• status: defines the type of status message. It can take two values: failed and ok. It must be present for the 'status' responses
• message: defines the message displayed in the alertbox. It must be present for the 'status' responses
• values: an array of values used to generate the rows in the interface. It must be present for the 'commands' responses
  • name: the title of the row, displayed on the left of the row
  • value: a subtitle, displayed on the right of the row
  • command: the command that will be launched if the row is touched by the user
• text: define a large block of text that will be displayed. It must be present for the 'text' responses

Graphs

Here is how a command output looks like to display a graph:

{
  "version" : 1,
  "title"   : "Index",
  "type"    : "commands",
  "status"  : "",
  "message" : "",
  "values"  : [
    {
      "name" : "Graph",
      "value" : "",
      "command" : "",
      "domain": "time (mn)",
      "range": "measured",
      "graph": "lineplot",
      "series":[
        {
          "label":"vals1",
          "values":[0, 1, 1, 2, 2, 0, 3, 5]
        },
        {
          "label":"vals2",
          "values":[0, 3, 1, 1, 2, 7, 3, 6]
        }
      ]
    }
  ],
}

All of the graph related keys are optional, you do not need them for normal commands:

• domain: the domain tag
• range: the range tag
• graph: the graph type, can be lineplot or barplot
• series: an array of number series that will be displayed on the same graph
  • label: the name corresponding to the serie's color in the legend
  • values: the values to display. The X and Y values are alterned in that way: [x1, y1, x2, y2, ...]

The colors on the graphs are generated automatically and depend on the number of series, and the order in which they appear

Response types

Commands

The application will create a table with a title defined by the 'title' attribute, and whose rows will be defined by the 'values' attribute.

Each row will display a text defined by 'name', and an optional subtext defined by 'value'. If the 'command' attribute is empty, the row is displayed with a flat background. If it is not empty, the row will be displayed as a button, and touching it will execute the command on the server, to retrieve another JSON response.

If the 'query' attribute is set, the application will display an alert box with a text field and a label defined by the 'query' attribute. The content of the text field will be concatenated to the command string before sending it to the server.

The command launched might not be a script stored in .pilotssh: any other script path (or script that can be found on the PATH) can be used, as long as it echoes a JSON text compatible with this API.

Status

The application will display an alertbox, with the title defined by the 'title' attribute, and the text defined by the 'message' attribute. The 'status' attribute will be used in a future version of the application.

Text

The application will display a large text zone, with the title defined by the 'title' attribute, and the content defined by the 'text' attribute. The 'text' attribute must contain base64 encoded data without wrap-around. Passing the text through the command base64 -w 0 encodes it correctly.