Common REST Service

Availability

Available since katl-commons 2.5.5.

Introduction

Since version 2.5.5, katl-commons exposes a REST service to facilitate arbitrary execution of SIL scripts. These services are available via HTTP POST at <your_base_url>/rest/keplerrominfo/refapp/latest/async-script and <your_base_url>/rest/keplerrominfo/refapp/latest/async. The service responses are all JSON formatted (see Beans below).

You will notice that most of the methods will schedule a task for execution and will provide a unique identifier for the task. You will have to call getResults and provide the identifier to check the status of the task (running or finished) and retrieve the results.

Authentication

Note that all the services require that the calling user is authenticated. You can use Basic authentication with your HTTP request.

Services

Method	Full Path	Availability
findScriptFiles	<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/findScriptFiles	4.0.0+
checkScript	<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/checkScript	4.0.0+
runScript	<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/runScript	4.0.0+
runDetachedScript	<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/runDetachedScript	4.0.0+
getResult	<your_base_url>/rest/keplerrominfo/refapp/latest/async/getResult	4.0.0+

findScriptFiles

Allows you to scan a folder for specific files for which the filename matches a specific regular expression.

Parameter	Type	Required	Description
dirPath	string	yes	The path of the directory to scan
regex	string	yes	The regular expression to match the filenames against

Returns a ScriptFileListResponse.

Example Request using AJS

AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/findScriptFiles",
 data : JSON.stringify({
 	dirPath : "D:/test",
    regex : "[^.]*\.sil"
 }),
 success : function(data) {
	console.log(data);
 },
 beforeSend: function (xhr){ 
	 xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password)); 
 }
});

Example JSON Response

{
 "files":[
   "D:\\test\\test_1234567890 - Copy (5).sil",
   "D:\\test\\test_1234567890 - Copy (6).sil",
   "D:\\test\\test_1234567890 - Copy.sil",
   "D:\\test\\test_1234567890.sil"
 ]
}

checkScript

Schedules a check script task to be run asynchronously for the given script and returns a ScriptScheduledResponse.

Parameter	Type	Required	Description
source	ScriptSource	yes	The script to check

Example Request using AJS

AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/checkScript",
 data : JSON.stringify({
   source : {
   	type: "file",
   	code: "return 1;"
 	}
 }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});

Example JSON Response

{
 "key" : 4
}

runScript

Schedules a run script task to be run asynchronously for the given script and returns a ScriptScheduledResponse.

Parameter	Type	Required	Description
source	ScriptSource	yes	The script to run

Example Request using AJS

AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/runScript",
 data : JSON.stringify({
   source: {
   	type: "file",
   	code: "return 1;"
	}
 }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});

Example JSON Response

{
 "key" : 4
}

runDetachedScript

Schedules a task to execute the script passed in as parameter on the server side and does not return the response or any information about it (simply runs the script).

Parameter	Type	Required	Description
source	ScriptSource	yes	The script to run

Example Request using AJS

AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/runDetachedScript",
 data : JSON.stringify({
   source: {
   	type: "file",
   	code: "return 1;"
 }
 }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});

Example JSON Response

null

getResult

Checks if the task identified by the provided id is still running or has finished and returns an AsyncResultResponse. If the task has finished execution, the result is removed from memory and returned in the response. Subsequent calls to this method will not return the result.

Parameter	Type	Required	Description
key	int	yes	The unique key identifying a scheduled task.

Example Request using AJS

AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async/getResult",
 data : JSON.stringify({
   key: 4
  }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});

Example JSON Response

{
 "running":false,
 "outcome": {
	 "valid": true
 }
}

Example JSON Response

{
 "running":false,
 "outcome" : {
 	"errors" : {
		0 : {
			"errLine":1
			"error":"Encountered <DOUBLE>  at line 1, column 13. Was expecting one of:  ";" , "." , "." "
		}
	}
 }
}

Beans

ScriptFileListResponse

Field	Type	Description
files	string []	List of absolute paths

AsyncResultResponse

Field	Type	Description
running	boolean	Signals that the script is still running
outcome	Object	The results

ScriptScheduledResponse

Field	Type	Description
key	int	The unique key of the scheduled task

ScriptSource

Field	Type	Description
type	string	The type of the source
code	string	The source code

CURL Example

The following curl calls show how you would call SIL scripts from your favourite system (that's Linux, I hope). The commands assume that username / password is 'admin'

Notice the way you pass multiple parameters to the SIL scripts. The logic is the same, you post the script to start running asynchronously, then you come back later for the results.

$curl -H "Content-Type: application/json" -u admin:admin -d " {\"source\" : { \"type\": \"file\", \"code\": \"return 1;\"}}" 192.168.19.250:7210/rest/keplerrominfo/refapp/latest/async-script/runScript
{"key":4}

$curl -H "Content-Type: application/json" -u admin:admin -d "{\"key\" : 3}" 192.168.19.250:7210/rest/keplerrominfo/refapp/latest/async/getResult 
{"running":false,"outcome":{"results":["1"]}}