che-server/agents/exec/docs/rest_api.md

REST API

Process API

Start a new process

Request

POST /process

• channel(optional) - the id of the channel which should be subscribed to the process events
• types(optional) - comma separated types works only in couple with specified channel, defines the events which will be sent by the process to the channel. Several values may be specified, e.g. channel=channel-1&types=stderr,stdout. By default channel will be subscribed to all the existing types(listed below). Possible type values:
  • stderr - output from the process stderr
  • stdout - output from the process stdout
  • process_status - the process status events(started, died)

{
    "name" : "build",
    "commandLine" : "mvn clean install",
    "type" : "maven"
}

Response

{
    "pid": 1,
    "name": "build",
    "commandLine": "mvn clean install",
    "type" : "maven",
    "alive": true,
    "nativePid": 9186
}

• 200 if successfully started
• 400 if incoming data is not valid e.g. name is empty
• 404 if specified channel doesn't exist
• 500 if any other error occurs

Get a process

Request

GET /process/{pid}

• pid - the id of the process to get

Response

{
    "pid": 1,
    "name": "build",
    "commandLine": "mvn clean install",
    "type" : "maven",
    "alive": false,
    "nativePid": 9186,
}

• 200 if response contains requested process
• 400 if pid is not valid, unsigned int required
• 404 if there is no such process
• 500 if any other error occurs

Kill a process

Request

DELETE /process/{pid}

• pid - the id of the process to kill

Response

{
    "pid": 1,
    "name": "build",
    "commandLine": "mvn clean install",
    "type" : "maven",
    "alive": true,
    "nativePid": 9186,
}

• 200 if successfully killed
• 400 if pid is not valid, unsigned int required
• 404 if there is no such process
• 500 if any other error occurs

Get process logs

Request

GET /process/{pid}/logs

• pid - the id of the process to get logs
• from(optional) - time to get logs from e.g. 2016-07-12T01:48:04.097980475+03:00 the format is RFC3339Nano don't forget to encode this query parameter
• till(optional) - time to get logs till e.g. 2016-07-12T01:49:04.097980475+03:00 the format is RFC3339Nano don't forget to encode this query parameter
• format(optional) - the format of the response, default is json, possible values are: text, json
• limit(optional) - the limit of logs in result, the default value is 50, logs are limited from the latest to the earliest
• skip (optional) - the logs to skip, default value is 0

Response

The result logs of the process with the command line printf "Hello\nWorld\n"

Text:

[STDOUT] 2016-07-04 08:37:56.315082296 +0300 EEST 	 Hello
[STDOUT] 2016-07-04 08:37:56.315128242 +0300 EEST 	 World

Json:

[
    {
        "Kind" : "STDOUT",
        "Time" : "2016-07-16T19:51:32.313368463+03:00",
        "Text" : "Hello"
    },
    {
        "Kind" : "STDOUT",
        "Time" : "2016-07-16T19:51:32.313603625+03:00",
        "Text" : "World"
    }
]

• 200 if logs are successfully fetched
• 400 if from or till format is invalid
• 404 if there is no such process
• 500 if any other error occurs

Get processes

Request

GET /process

• all(optional) - if true then all the processes including dead ones will be returned(respecting paging ofc), otherwise only alive processes will be returnedg

Response

The result of the request GET /process?all=true

[
    {
        "pid": 1,
        "name": "build",
        "commandLine": "mvn clean install",
        "type" : "maven",
        "alive": true,
        "nativePid": 9186,
    },
    {
        "pid": 2,
        "name": "build",
        "commandLine": "printf \"Hello World\"",
        "alive": false,
        "nativePid": 9588
    }
]

• 200 if processes are successfully retrieved
• 500 if any error occurs

Subscribe to the process events

Request

POST /process/{pid}/events/{channel}

• pid - the id of the process to subscribe to
• channel - the id of the webscoket channel which is subscriber
• types(optional) - the types of the events separated by comma e.g. ?types=stderr,stdout
• after(optional) - process logs which appeared after given time will be republished to the channel. This method may be useful in the reconnect process

Response

• 200 if successfully subscribed
• 400 if any of the parameters is not valid
• 404 if there is no such process or channel
• 500 if any other error occurs

Unsubscribe from the process events

Request

DELETE /process/{pid}/events/{channel}

• pid - the id of the process to unsubscribe from
• channel - the id of the webscoket channel which currenly subscribed to the process events

Response

• 200 if successfully unsubsribed
• 400 if any of the parameters is not valid
• 404 if there is no such process or channel
• 500 if any other error occurs

Update the process events subscriber

Request

PUT /process/{pid}/events/{channel}

• pid - the id of the process
• channel - the id of the websocket channel which is subscriber
• types - the types of the events separated with comma e.g. ?types=stderr,stdout

Response

• 200 if successfully updated
• 400 if any of the parameters is not valid
• 404 if there is no such process or channel
• 500 if any other error occurs