API Details

The plugin is intended to work with any application, client or server side, that can respond to an request using the following variables.

Request

Variables

Prefix variables with "&", postfix with "=", see examples.

Row/column metadata

row_labels - [(true)/false] - return row labels for window requested, true when not provided
column_labels - [(true)/false] - return column labels for window request, true when not provided

Window defining

x1=int,x2=nil,y1=nil,y2=nil            -> return all cells in the row defined by x1
x1,x2                                  -> return the rows in range x1-x2 (inclusive)
y1                                     -> return all cells in this column    
y1,y2                                  -> return the columns in range y1-y2
x1,y1                                  -> return the cell at x1,y1
x1,y1,x2,y2                            -> return the cells bound by (x1,y1), (x2,y2)

A value of -1 for a parameter will qualify as being null. The parameters that are ignored will also be considered as null.

Request variable summary

 metadata_only = [true/(false)] - don't return the cell values, just the pertinent metadata, used to stub the matrix
 matrix - [true/(false)] - return all possible metadata properties for the matrix: key
 row - [true/(false)] - return all possible metadata properties for the row: key
 column - [true/(false)] - return all possible metadata properties for the column: key

 x1 - [positive integer] - row/upper left co-ordinate
 y1 - [positive integer] - column/upper left co-ordinate
 x2 - [positive integer] - row range/bottom right co-ordinate
 y2 - [positive integer] - column range/bottom left co-ordinate
 

Response

All responses are in JSON.

A response is a single hash with the following keys possible:

• matrix: (metadata properties of matrix)
  • name
  • other metadata
• row: (metadata properties for the returned row)
  • labels (hash of row_index => row_name)
• column: (metadata properties for the returned columns)
  • labels
• data: arrayOfArrays that points to a hash:

      {
        state1: {properties},
        state2: {properties},
        stateN: {properties},
        value: {properties}
      }  

Examples

Request: http://foo.org/path/to/api_action?x1=1&y1=1&x2=100&y2=50

Response:

{
  "matrix": {
    "height": 1000,
    "width": 1000
  },
  "row": {
    "labels": ["label1", "label2", ..., "label100"]
  },
  "column": {
    "labels": ["label1", "label2", ..., "label50"]
  },
  "data": [
    [
      {
        "author": "XYZ",
        "date": "YYYYMMDDhhmm",
        "value": 100
      },
      {data_{1,2}},
      .
      .
      .
      {data_{1,50}}
    ],
    [data_2],
    .
    .
    .
    [data_100]
  ]
}

The requests can also be for metadata only. In this case, the response is similar but without the cell key in the data ArrayOfArrays. A configuration for using jMatrixBrowse to handle these requests and responses should specify the 'author' and 'date' as layers which would then be handled accordingly.