Difference between revisions of "Management APIs"

From i2Rest
Jump to: navigation, search
(Created page with "{{DISPLAYTITLE:Management APIs}} = Management APIs =")
 
m (→‎Management APIs)
 
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:Management APIs}}
 
{{DISPLAYTITLE:Management APIs}}
 
= Management APIs =
 
= Management APIs =
 +
Management APIs includes functions that can be used to do some management stuff - change runtime parameters, query current status of server instance, etc. OAuth2 token with [[i2Rest scopes#management_functions|management_functions]] scope is required for any Management Api call.<br>
 +
All the Management APIs are available on [[i2Rest Gates#management_gate|Management Gate endpoint]]. The URL is as follows:
 +
 +
<pre>http[s]://<your_i2Rest_server></pre>
 +
where:
 +
* <tt>your_i2Rest_server</tt> - host name and optional port of management gate of the i2Rest Server instance (defined in [[Gate_object|Management Gate Config]])
 +
 +
example:
 +
<pre>https://192.168.0.233:8080</pre>
 +
Please look at our guides on how to obtain [[Auth_profile_SoapUI|Oauth2 token]] and than perform [[Managment_API_SoapUI|Managment api authorized call]] using Soap UI.
 +
== STATUS API ==
 +
This API returns status details of runing server instance.
 +
=== STATUS API parameters ===
 +
To call STATUS API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "STATUS" must be specified.<br/>
 +
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|gate
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''OPTIONAL, server to be requested for status details'''<br/>
 +
The following options are acceptable:<br>
 +
* <tt>"main" - for Main Gate server</tt>
 +
* <tt>"session" - for Session Gate server</tt>
 +
* <tt>"management" - for Management Gate server</tt>
 +
* <tt>"core" - for i2Rest server core</tt>
 +
|With no "gate" parameter specified, status details of each of represanting i2Rest Gate servers will be returned.
 +
|}
 +
 +
=== STATUS example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer nLkd-NlP1rsXwrhIHS6bZ559Jb-4yIQUIDweQb8GhKQ
 +
Content-Length: 39
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"status",
 +
"gate":"main"
 +
}
 +
 +
</pre>
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 650
 +
Connection: keep-alive
 +
 +
{
 +
  "main": {
 +
    "server_name": "Main",
 +
    "master_link": "https://i2rest.com:22088",
 +
    "manager_link": "file:///tmp/QACXQ6D802",
 +
    "clients_max": 50,
 +
    "clients": 0,
 +
    "clients_peak": 6,
 +
    "clients_refused": 0,
 +
    "workers": 5,
 +
    "workers_peak": 5,
 +
    "workers_min": 5,
 +
    "workers_max": 50,
 +
    "busy_workers": 1,
 +
    "busy_workers_peak": 5,
 +
    "queue": 0,
 +
    "queue_peak": 4,
 +
    "timeout": 30000,
 +
    "debug": 7,
 +
    "syslog": "udp://localhost:514",
 +
    "multithreaded": true,
 +
    "manager_requests": 0,
 +
    "master_requests": 35,
 +
    "manager_errors": 0,
 +
    "master_errors": 1,
 +
    "tpm_master": 0,
 +
    "tpm_manager": 0
 +
  }
 +
}
 +
</pre>
 +
 +
== ADD_PCML API ==
 +
This API allows you to publish PCML file to the running i2Rest Server instance .
 +
 +
=== ADD_PCML API parameters ===
 +
To call ADD_PCML API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "ADD_PCML" must be specified.<br/>
 +
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|pcml_mount
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REUQIRED, PCML API mount point'''<br/>
 +
Defines PCML API mounting point. This parameter will be used as a part of URL where this PCML API will be accessible:<br/><br/>
 +
<tt>http[s]://<Main Gate>/<<b>Mount Point</b>>/<Program Name></tt><br/><br/>
 +
Example:<br/>
 +
<tt>"pcml_mount":"<b>echo</b>" -> <nowiki>https://i2rest.com/</nowiki><b>echo</b>/echo</tt><br/>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|pcml_file
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REUQIRED, path to PCML API definition file'''<br/>
 +
Path to file with PCML API definition. Path can be specified as absolute path or as path relative to [[I2Rest_Config#curdir|current directory]] of i2Rest Server instance. <br/><br/>
 +
Example:
 +
<tt>"pcml_file":"/i2rest/Server1/echo.pcml"</tt><br/><br/>
 +
|
 +
|}
 +
 +
=== ADD_PCML example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer nriMv5f-87-h8jxsLw9nGVsOdcvh5cn2dd2m4RPqnxA
 +
Content-Length: 92
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
    "command":"ADD_PCML",
 +
    "pcml_mount":"echo",
 +
    "pcml_file":"/PCMLs/echo.pcml"
 +
}
 +
</pre>
 +
 +
response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 45
 +
Connection: keep-alive
 +
 +
{
 +
  "status": "OK",
 +
  "details": "Compiled"
 +
}
 +
</pre>
 +
 +
== DEL_PCML API ==
 +
This API removes PCML file from the list of PCML files on the running i2Rest Server instance.
 +
=== DEL_PCML API parameters ===
 +
To call DEL_PCML API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "DEL_PCML" must be specified.<br/>
 +
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|pcml_mount
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REUQIRED, PCML API mount point'''<br/>
 +
Defines PCML API mounting point. This parameter will be used as a part of URL where this PCML API will be accessible:<br/><br/>
 +
<tt>http[s]://<Main Gate>/<<b>Mount Point</b>>/<Program Name></tt><br/><br/>
 +
Example:<br/>
 +
<tt>"pcml_mount":"<b>echo</b>" -> <nowiki>https://i2rest.com/</nowiki><b>echo</b>/echo</tt><br/>
 +
|
 +
|}
 +
 +
=== DEL_PCML example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer 9zFcSNQxvCFICdHYCz3eYx0I8w45yFLY139CgnbkMo8
 +
Content-Length: 48
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
    "command":"ADD_PCML",
 +
    "pcml_mount":"echo",
 +
}
 +
</pre>
 +
 +
response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 44
 +
Connection: keep-alive
 +
 +
{
 +
  "status": "OK",
 +
  "details": "Deleted"
 +
}
 +
</pre>
 +
 +
== CLIENTS API ==
 +
This API returns status details of the clients connections to i2Rest Gate servers.
 +
=== CLIENTS API parameters ===
 +
To call CLIENTS API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "CLIENTS"  must be specified.<br/>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|gate
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''OPTIONAL, server to watch for clients connections on'''<br/>
 +
The following options are acceptable:<br>
 +
* <tt>"main" - for Main Gate server</tt>
 +
* <tt>"session" - for Session Gate server</tt>
 +
* <tt>"management" - for Management Gate server</tt>
 +
|style="padding: 5px"|With no "gate" parameter specified, clients connections of each of represanting i2Rest Gate servers will be returned.
 +
|}
 +
 +
=== CLIENTS API example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer nWYo_kp-UxMLjnEMhZp7yv6EUA-jNdEg66pz54woSDA
 +
Content-Length: 46
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"CLIENTS",
 +
"gate":"management"
 +
}
 +
</pre>
 +
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 276
 +
Connection: keep-alive
 +
 +
{
 +
  "management": {
 +
    "clients": [
 +
      {
 +
        "busy": true,
 +
        "socket": 24,
 +
        "management": false,
 +
        "timeout": 30000
 +
      },
 +
      {
 +
        "busy": true,
 +
        "socket": 26,
 +
        "management": true,
 +
        "timeout": 30000
 +
      }
 +
    ]
 +
  }
 +
}
 +
</pre>
 +
 +
== GET_OPENAPI30 API ==
 +
This API returns OpenAPI 3.0 tag content of specified PCML mounting point.
 +
=== GET_OPENAPI30 API parameters ===
 +
To call GET_OPENAPI30 API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "GET_OPENAPI30" must be specified.<br/>
 +
The string containing command to call. This command "as is" will be called in session job
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|pcml_mount
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REUQIRED, PCML API mount point'''<br/>
 +
Defines PCML API mounting point. This parameter will be used as a part of URL where this PCML API will be accessible:<br/><br/>
 +
<tt>http[s]://<Main Gate>/<<b>Mount Point</b>>/<Program Name></tt><br/><br/>
 +
Example:<br/>
 +
<tt>"pcml_mount":"<b>echo</b>" -> <nowiki>https://i2rest.com/</nowiki><b>echo</b>/echo</tt><br/>
 +
|
 +
|}
 +
=== GET_OPENAPI30 API example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer vIxev5AI0cCmx-p-sGKD4iUZ1qZoZzutnvDoVR_919w
 +
Content-Length: 51
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"GET_OPENAPI30",
 +
"pcml_mount":"echo2"
 +
}
 +
</pre>
 +
 +
response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 5292
 +
Connection: keep-alive
 +
 +
{
 +
  "openapi": "3.0.0",
 +
  "tags": [
 +
    {
 +
      "name": "itag1",
 +
      "description": "Tag1"
 +
    },
 +
    {
 +
      "name": "itag2",
 +
      "description": "Tag2"
 +
    }
 +
  ],
 +
  "info": {
 +
    "title": "Title...",
 +
    "description": "Description...",
 +
    "termsOfService": "http://terms.of.service",
 +
    "version": "1.0.0",
 +
    "contact": {
 +
      "name": "Name",
 +
      "url": "http://Name",
 +
      "email": "Name@name.com"
 +
    },
 +
    "license": {
 +
      "name": "Name",
 +
      "url": "http://Name"
 +
    }
 +
  },
 +
  "servers": [
 +
    {
 +
      "url": "https://i2rest.com:22088",
 +
      "description": "i2Rest instance"
 +
    }
 +
  ],
 +
  "components": {
 +
    "schemas": {
 +
      "errorResponse": {
 +
        "type": "object",
 +
        "properties": {
 +
          "status": {
 +
            "type": "string"
 +
          },
 +
...
 +
}
 +
</pre>
 +
 +
== PCMLS API ==
 +
This API returns a list of run_program API defenitions (PCML files) that are loaded on running i2Rest server instance.
 +
=== PCMLS API parameters ===
 +
To call PCMLS API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "PCMLS" must be specified.<br/>
 +
|
 +
|}
 +
=== PCMLS example ===
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer 9zFcSNQxvCFICdHYCz3eYx0I8w45yFLY139CgnbkMo8
 +
Content-Length: 22
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
    "command":"PCMLS"
 +
}
 +
</pre>
 +
 +
response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 561
 +
Connection: keep-alive
 +
 +
[
 +
  {
 +
    "pcml_mount": "echo",
 +
    "pcml_file": "pcml/echo.pcml",
 +
    "pcml_id": 1,
 +
    "pcml_bin_length": 244,
 +
    "valid_in_anonymous": true,
 +
    "compiled": "2020-05-19T16:17:27+0300",
 +
    "last_used": "1970-01-01T03:00:00+0300",
 +
    "calls": 0,
 +
    "errors": 0
 +
  },
 +
  {
 +
    "pcml_mount": "QSYRUSRI",
 +
    "pcml_file": "/home/btpl/JPCML/QSYRUSRI.pcml",
 +
    "pcml_id": 2,
 +
    "pcml_bin_length": 1100,
 +
    "valid_in_anonymous": true,
 +
    "compiled": "2020-05-19T16:17:27+0300",
 +
    "last_used": "1970-01-01T03:00:00+0300",
 +
    "calls": 0,
 +
    "errors": 0
 +
  }
 +
]
 +
</pre>
 +
 +
== SESSIONS API ==
 +
This API returns list of submitted sessions.
 +
=== SESSIONS API parameters ===
 +
To call SESSIONS API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "SESSIONS" must be specified.<br/>
 +
|
 +
|}
 +
 +
=== SESSIONS API example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer fBaERS2CmNvmapOW50aGyliHvae6ogEiqRg0DXYhOyI
 +
Content-Length: 25
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"sessions"
 +
}
 +
</pre>
 +
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 1318
 +
Connection: keep-alive
 +
 +
[
 +
  {
 +
    "session": "3a46d002-2717-1a49-ab93-0004ac19a205",
 +
    "job": "069349/BTPL/I2RESTA",
 +
    "ready": true,
 +
    "busy": false,
 +
    "anonymous": true,
 +
    "submitted": "2020-05-21T16:16:35+0300",
 +
    "started": "2020-05-21T16:16:39+0300",
 +
    "last_call": "2020-05-21T16:16:39+0300",
 +
    "requests": 0,
 +
    "errors": 0
 +
  },
 +
  {
 +
    "session": "3b01b002-2717-1a49-ab93-0004ac19a205",
 +
    "job": "069350/BTPL/I2RESTA",
 +
    "ready": true,
 +
    "busy": false,
 +
    "anonymous": true,
 +
    "submitted": "2020-05-21T16:16:35+0300",
 +
    "started": "2020-05-21T16:16:39+0300",
 +
    "last_call": "2020-05-21T16:16:39+0300",
 +
    "requests": 0,
 +
    "errors": 0
 +
  },
 +
  {
 +
    "session": "3b149002-2717-1a49-ab93-0004ac19a205",
 +
    "job": "069351/BTPL/I2RESTA",
 +
    "ready": true,
 +
    "busy": false,
 +
    "anonymous": true,
 +
    "submitted": "2020-05-21T16:16:35+0300",
 +
    "started": "2020-05-21T16:16:39+0300",
 +
    "last_call": "2020-05-21T16:16:39+0300",
 +
    "requests": 0,
 +
    "errors": 0
 +
  },
 +
  {
 +
    "session": "fBaERS2CmNvmapOW50aGyliHvae6ogEiqRg0DXYhOyI",
 +
    "job": "069352/BTPL/I2RESTS",
 +
    "ready": true,
 +
    "busy": false,
 +
    "anonymous": false,
 +
    "submitted": "2020-05-21T16:17:39+0300",
 +
    "started": "2020-05-21T16:17:40+0300",
 +
    "last_call": "2020-05-21T16:18:03+0300",
 +
    "requests": 2,
 +
    "errors": 0
 +
  }
 +
]
 +
</pre>
 +
 +
== DEBUG API ==
 +
With this API you can change URL of syslog server and message severity level to be logged at console or syslog. Each i2Rest gate and i2Rest server core can have its own separate level of logging.
 +
=== DEBUG API parameters ===
 +
To call DEBUG API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "DEBUG" must be specified.<br/>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|level
 +
|style="padding: 5px"|integer
 +
|style="padding: 5px"|'''REQUIRED, message severity level to be logged'''<br/>
 +
Minimum level of message severity which will be logged at console or syslog.The following options are acceptable:<br>
 +
* <tt>0 - Emergency</tt>
 +
* <tt>1 - Alert</tt>
 +
* <tt>2 - Critical</tt>
 +
* <tt>3 - Error</tt>
 +
* <tt>4 - Warning</tt>
 +
* <tt>5 - Notice</tt>
 +
* <tt>6 - Info</tt>
 +
* <tt>7 - Full</tt>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|gate
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''OPTIONAL, server to redefine debug level or syslog server on'''<br/>
 +
The following options are acceptable:<br>
 +
* <tt>"main" - for Main Gate server</tt>
 +
* <tt>"session" - for Session Gate server</tt>
 +
* <tt>"management" - for Management Gate server</tt>
 +
* <tt>"core" - for i2Rest server core</tt>
 +
|With no "gate" parameter specified,  each of represanting i2Rest Gate servers and I2rest server core will be affected.
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|syslog
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''OPTIONAL, URL of syslog server'''<br/>
 +
UDP or to TCP-IP syslog endpoints to send i2Rest logging messages.<br/><br/>
 +
Examples:<br/>
 +
* <tt><nowiki>udp://localhost:514</nowiki></tt>
 +
* <tt><nowiki>http://localhost:1234</nowiki></tt>
 +
|
 +
|}
 +
 +
=== DEBUG example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer YMtT6i4HpItTm171L-PVWj9PPPtICznxJWeuhrHT_KA
 +
Content-Length: 83
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"debug",
 +
"syslog":"udp://localhost:515",
 +
"level":6,
 +
"gate":"main"
 +
}
 +
</pre>
 +
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 60
 +
Connection: keep-alive
 +
 +
{
 +
  "status": "OK",
 +
  "details": "Debug level was changed"
 +
}
 +
</pre>
 +
 +
== CLIENTS+/- API ==
 +
This API allows you to adjust "clients_max" parameter of [[Gate_object|Gate Object]] (the highest amount of incoming connections) on running server istance (each of representing i2Rest Gate servers). CLIENTS+ API call will increase "clients_max" parameter value by specified number, CLIENTS- API call will decrease "clients_max" parameter value by specified number.
 +
=== CLIENTS+/- API parameters ===
 +
To call CLIENTS+/- API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "CLIENTS+" or "CLIENTS-"  must be specified.<br/>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|gate
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''OPTIONAL, server to adjust "clients_max" parameter on'''<br/>
 +
The following options are acceptable:<br>
 +
* <tt>"main" - for Main Gate server</tt>
 +
* <tt>"session" - for Session Gate server</tt>
 +
* <tt>"management" - for Management Gate server</tt>
 +
|style="padding: 5px"|With no "gate" parameter specified, "clients_max" parameter of each of represanting i2Rest Gate servers will be adjusted.
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|number
 +
|style="padding: 5px"|integer
 +
|style="padding: 5px"|'''OPTIONAL, value to increase/decrease "clients_max" parameter'''<br/>
 +
|style="padding: 5px"|1
 +
|}
 +
 +
=== CLIENTS API example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer VKys2XfGTeykM1m62767KvvJuHLgkhNp_-74LXtaLsc
 +
Content-Length: 49
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"CLIENTS+",
 +
"gate":"main"
 +
}
 +
</pre>
 +
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 68
 +
Connection: keep-alive
 +
 +
{
 +
  "status": "OK",
 +
  "details": "CLIENTS+/- command was accepted"
 +
}
 +
</pre>
 +
 +
== WORKER+/- API ==
 +
This API allows you to adjust amount of "worker" threads on each of representing [[I2Rest_Gates|i2Rest Gate]] servers. WORKER+ API call will increase amount of "worker" threads by specified number, WORKER- API call will decrease amount of "worker" threads by specified number.
 +
=== WORKER+/- API parameters ===
 +
To call WORKER+/- API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "WORKER+" or "WORKER-"  must be specified.<br/>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|gate
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''OPTIONAL, server to adjust worker threads amount on'''<br/>
 +
|
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|number
 +
|style="padding: 5px"|integer
 +
|style="padding: 5px"|'''OPTIONAL, number of threads to add/remove'''<br/>
 +
|style="padding: 5px"|1
 +
|}
 +
 +
=== WORKER+/- example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer nWYo_kp-UxMLjnEMhZp7yv6EUA-jNdEg66pz54woSDA
 +
Content-Length: 24
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"WORKER+"
 +
}
 +
</pre>
 +
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 72
 +
Connection: keep-alive
 +
 +
{
 +
  "status": "OK",
 +
  "details": "Add worker(s) command was submitted"
 +
}
 +
</pre>
 +
 +
== ANONYMOUS+ API ==
 +
This API submits anonymous session.
 +
=== ANONYMOUS+ API parameters ===
 +
To call ANONYMOUS+ API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "ANONYMOUS+" must be specified.<br/>
 +
|
 +
|}
 +
=== ANONYMOUS+ example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer nWYo_kp-UxMLjnEMhZp7yv6EUA-jNdEg66pz54woSDA
 +
Content-Length: 27
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"ANONYMOUS+"
 +
}
 +
</pre>
 +
 +
Response:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 137
 +
Connection: keep-alive
 +
 +
{
 +
  "status": "OK",
 +
  "details": "Session started",
 +
  "session": "8df78002-124d-1a49-ab93-0004ac19a205",
 +
  "job": "068154/BTPL/I2RESTA"
 +
}
 +
</pre>
 +
 +
== STOP API ==
 +
This API stops server instance.
 +
=== STOP API parameters ===
 +
To call STOP API, you must send POST request with following JSON object as request body (media type 'application/json'):
 +
{| style="width: 100%; vertical-align:top; border-collapse:collapse" border="1"
 +
| style="width: 10%; padding: 5px"|'''Field'''
 +
| style="width: 10%; padding: 5px"|'''Type'''
 +
| style="width: 40%; padding: 5px"|'''Description'''
 +
| style="width: 40%; padding: 5px"|'''Default value'''
 +
|-style="vertical-align:top;"
 +
|style="padding: 5px"|command
 +
|style="padding: 5px"|string
 +
|style="padding: 5px"|'''REQUIRED''', "STOP" must be specified.<br/>
 +
|
 +
|}
 +
 +
=== STOP example ===
 +
Request:
 +
<pre>
 +
POST https://192.168.0.233:8080/ HTTP/1.1
 +
Accept-Encoding: gzip,deflate
 +
Content-Type: application/json
 +
Authorization: Bearer YMtT6i4HpItTm171L-PVWj9PPPtICznxJWeuhrHT_KA
 +
Content-Length: 21
 +
Host: 192.168.0.233:8080
 +
Connection: Keep-Alive
 +
 +
{
 +
"command":"STOP"
 +
}
 +
</pre>
 +
Responce:
 +
<pre>
 +
HTTP/1.1 200 OK
 +
Server: i2Rest/1.0
 +
X-Frame-Options: SAMEORIGIN
 +
Content-Type: application/json; charset=utf-8
 +
Content-Length: 62
 +
Connection: close
 +
 +
{
 +
  "status": "OK",
 +
  "details": "Stop command was accepted"
 +
}
 +
</pre>
 +
 +
----
 +
[[I2Rest_API|Back to i2Rest API]]

Latest revision as of 20:13, 2 November 2021

Management APIs

Management APIs includes functions that can be used to do some management stuff - change runtime parameters, query current status of server instance, etc. OAuth2 token with management_functions scope is required for any Management Api call.
All the Management APIs are available on Management Gate endpoint. The URL is as follows: 

http[s]://<your_i2Rest_server>

where:

  • your_i2Rest_server - host name and optional port of management gate of the i2Rest Server instance (defined in Management Gate Config)

example: 

https://192.168.0.233:8080

Please look at our guides on how to obtain Oauth2 token and than perform Managment api authorized call using Soap UI.

STATUS API

This API returns status details of runing server instance.

STATUS API parameters

To call STATUS API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "STATUS" must be specified.
gate string OPTIONAL, server to be requested for status details

The following options are acceptable:

  • "main" - for Main Gate server
  • "session" - for Session Gate server
  • "management" - for Management Gate server
  • "core" - for i2Rest server core
 With no "gate" parameter specified, status details of each of represanting i2Rest Gate servers will be returned.

STATUS example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer nLkd-NlP1rsXwrhIHS6bZ559Jb-4yIQUIDweQb8GhKQ
Content-Length: 39
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"status",
	"gate":"main"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 650
Connection: keep-alive

{
  "main": {
    "server_name": "Main",
    "master_link": "https://i2rest.com:22088",
    "manager_link": "file:///tmp/QACXQ6D802",
    "clients_max": 50,
    "clients": 0,
    "clients_peak": 6,
    "clients_refused": 0,
    "workers": 5,
    "workers_peak": 5,
    "workers_min": 5,
    "workers_max": 50,
    "busy_workers": 1,
    "busy_workers_peak": 5,
    "queue": 0,
    "queue_peak": 4,
    "timeout": 30000,
    "debug": 7,
    "syslog": "udp://localhost:514",
    "multithreaded": true,
    "manager_requests": 0,
    "master_requests": 35,
    "manager_errors": 0,
    "master_errors": 1,
    "tpm_master": 0,
    "tpm_manager": 0
  }
}

ADD_PCML API

This API allows you to publish PCML file to the running i2Rest Server instance .

ADD_PCML API parameters

To call ADD_PCML API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "ADD_PCML" must be specified.
pcml_mount string REUQIRED, PCML API mount point

Defines PCML API mounting point. This parameter will be used as a part of URL where this PCML API will be accessible:

http[s]://<Main Gate>/<Mount Point>/<Program Name>

Example:
"pcml_mount":"echo" -> https://i2rest.com/echo/echo
pcml_file string REUQIRED, path to PCML API definition file

Path to file with PCML API definition. Path can be specified as absolute path or as path relative to current directory of i2Rest Server instance.

Example: "pcml_file":"/i2rest/Server1/echo.pcml"

ADD_PCML example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer nriMv5f-87-h8jxsLw9nGVsOdcvh5cn2dd2m4RPqnxA
Content-Length: 92
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
     "command":"ADD_PCML",
     "pcml_mount":"echo",
     "pcml_file":"/PCMLs/echo.pcml"
}

response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 45
Connection: keep-alive

{
  "status": "OK",
  "details": "Compiled"
}

DEL_PCML API

This API removes PCML file from the list of PCML files on the running i2Rest Server instance.

DEL_PCML API parameters

To call DEL_PCML API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "DEL_PCML" must be specified.
pcml_mount string REUQIRED, PCML API mount point

Defines PCML API mounting point. This parameter will be used as a part of URL where this PCML API will be accessible:

http[s]://<Main Gate>/<Mount Point>/<Program Name>

Example:
"pcml_mount":"echo" -> https://i2rest.com/echo/echo

DEL_PCML example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer 9zFcSNQxvCFICdHYCz3eYx0I8w45yFLY139CgnbkMo8
Content-Length: 48
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
     "command":"ADD_PCML",
     "pcml_mount":"echo",
}

response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 44
Connection: keep-alive

{
  "status": "OK",
  "details": "Deleted"
}

CLIENTS API

This API returns status details of the clients connections to i2Rest Gate servers.

CLIENTS API parameters

To call CLIENTS API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "CLIENTS" must be specified.
gate string OPTIONAL, server to watch for clients connections on

The following options are acceptable:

  • "main" - for Main Gate server
  • "session" - for Session Gate server
  • "management" - for Management Gate server
 With no "gate" parameter specified, clients connections of each of represanting i2Rest Gate servers will be returned.

CLIENTS API example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer nWYo_kp-UxMLjnEMhZp7yv6EUA-jNdEg66pz54woSDA
Content-Length: 46
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"CLIENTS",
	"gate":"management"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 276
Connection: keep-alive

{
  "management": {
    "clients": [
      {
        "busy": true,
        "socket": 24,
        "management": false,
        "timeout": 30000
      },
      {
        "busy": true,
        "socket": 26,
        "management": true,
        "timeout": 30000
      }
    ]
  }
}

GET_OPENAPI30 API

This API returns OpenAPI 3.0 tag content of specified PCML mounting point.

GET_OPENAPI30 API parameters

To call GET_OPENAPI30 API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "GET_OPENAPI30" must be specified.

The string containing command to call. This command "as is" will be called in session job

pcml_mount string REUQIRED, PCML API mount point

Defines PCML API mounting point. This parameter will be used as a part of URL where this PCML API will be accessible:

http[s]://<Main Gate>/<Mount Point>/<Program Name>

Example:
"pcml_mount":"echo" -> https://i2rest.com/echo/echo

GET_OPENAPI30 API example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer vIxev5AI0cCmx-p-sGKD4iUZ1qZoZzutnvDoVR_919w
Content-Length: 51
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"GET_OPENAPI30",
	"pcml_mount":"echo2"
}

response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 5292
Connection: keep-alive

{
  "openapi": "3.0.0",
  "tags": [
    {
      "name": "itag1",
      "description": "Tag1"
    },
    {
      "name": "itag2",
      "description": "Tag2"
    }
  ],
  "info": {
    "title": "Title...",
    "description": "Description...",
    "termsOfService": "http://terms.of.service",
    "version": "1.0.0",
    "contact": {
      "name": "Name",
      "url": "http://Name",
      "email": "Name@name.com"
    },
    "license": {
      "name": "Name",
      "url": "http://Name"
    }
  },
  "servers": [
    {
      "url": "https://i2rest.com:22088",
      "description": "i2Rest instance"
    }
  ],
  "components": {
    "schemas": {
      "errorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
...
}

PCMLS API

This API returns a list of run_program API defenitions (PCML files) that are loaded on running i2Rest server instance.

PCMLS API parameters

To call PCMLS API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "PCMLS" must be specified.

PCMLS example

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer 9zFcSNQxvCFICdHYCz3eYx0I8w45yFLY139CgnbkMo8
Content-Length: 22
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
     "command":"PCMLS"
}

response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 561
Connection: keep-alive

[
  {
    "pcml_mount": "echo",
    "pcml_file": "pcml/echo.pcml",
    "pcml_id": 1,
    "pcml_bin_length": 244,
    "valid_in_anonymous": true,
    "compiled": "2020-05-19T16:17:27+0300",
    "last_used": "1970-01-01T03:00:00+0300",
    "calls": 0,
    "errors": 0
  },
  {
    "pcml_mount": "QSYRUSRI",
    "pcml_file": "/home/btpl/JPCML/QSYRUSRI.pcml",
    "pcml_id": 2,
    "pcml_bin_length": 1100,
    "valid_in_anonymous": true,
    "compiled": "2020-05-19T16:17:27+0300",
    "last_used": "1970-01-01T03:00:00+0300",
    "calls": 0,
    "errors": 0
  }
]

SESSIONS API

This API returns list of submitted sessions.

SESSIONS API parameters

To call SESSIONS API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "SESSIONS" must be specified.

SESSIONS API example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer fBaERS2CmNvmapOW50aGyliHvae6ogEiqRg0DXYhOyI
Content-Length: 25
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"sessions"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 1318
Connection: keep-alive

[
  {
    "session": "3a46d002-2717-1a49-ab93-0004ac19a205",
    "job": "069349/BTPL/I2RESTA",
    "ready": true,
    "busy": false,
    "anonymous": true,
    "submitted": "2020-05-21T16:16:35+0300",
    "started": "2020-05-21T16:16:39+0300",
    "last_call": "2020-05-21T16:16:39+0300",
    "requests": 0,
    "errors": 0
  },
  {
    "session": "3b01b002-2717-1a49-ab93-0004ac19a205",
    "job": "069350/BTPL/I2RESTA",
    "ready": true,
    "busy": false,
    "anonymous": true,
    "submitted": "2020-05-21T16:16:35+0300",
    "started": "2020-05-21T16:16:39+0300",
    "last_call": "2020-05-21T16:16:39+0300",
    "requests": 0,
    "errors": 0
  },
  {
    "session": "3b149002-2717-1a49-ab93-0004ac19a205",
    "job": "069351/BTPL/I2RESTA",
    "ready": true,
    "busy": false,
    "anonymous": true,
    "submitted": "2020-05-21T16:16:35+0300",
    "started": "2020-05-21T16:16:39+0300",
    "last_call": "2020-05-21T16:16:39+0300",
    "requests": 0,
    "errors": 0
  },
  {
    "session": "fBaERS2CmNvmapOW50aGyliHvae6ogEiqRg0DXYhOyI",
    "job": "069352/BTPL/I2RESTS",
    "ready": true,
    "busy": false,
    "anonymous": false,
    "submitted": "2020-05-21T16:17:39+0300",
    "started": "2020-05-21T16:17:40+0300",
    "last_call": "2020-05-21T16:18:03+0300",
    "requests": 2,
    "errors": 0
  }
]

DEBUG API

With this API you can change URL of syslog server and message severity level to be logged at console or syslog. Each i2Rest gate and i2Rest server core can have its own separate level of logging.

DEBUG API parameters

To call DEBUG API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "DEBUG" must be specified.
level integer REQUIRED, message severity level to be logged

Minimum level of message severity which will be logged at console or syslog.The following options are acceptable:

  • 0 - Emergency
  • 1 - Alert
  • 2 - Critical
  • 3 - Error
  • 4 - Warning
  • 5 - Notice
  • 6 - Info
  • 7 - Full
gate string OPTIONAL, server to redefine debug level or syslog server on

The following options are acceptable:

  • "main" - for Main Gate server
  • "session" - for Session Gate server
  • "management" - for Management Gate server
  • "core" - for i2Rest server core
 With no "gate" parameter specified, each of represanting i2Rest Gate servers and I2rest server core will be affected.
syslog string OPTIONAL, URL of syslog server

UDP or to TCP-IP syslog endpoints to send i2Rest logging messages.

Examples:

  • udp://localhost:514
  • http://localhost:1234

DEBUG example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer YMtT6i4HpItTm171L-PVWj9PPPtICznxJWeuhrHT_KA
Content-Length: 83
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"debug",
	"syslog":"udp://localhost:515",
	"level":6,
	"gate":"main"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 60
Connection: keep-alive

{
  "status": "OK",
  "details": "Debug level was changed"
}

CLIENTS+/- API

This API allows you to adjust "clients_max" parameter of Gate Object (the highest amount of incoming connections) on running server istance (each of representing i2Rest Gate servers). CLIENTS+ API call will increase "clients_max" parameter value by specified number, CLIENTS- API call will decrease "clients_max" parameter value by specified number.

CLIENTS+/- API parameters

To call CLIENTS+/- API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "CLIENTS+" or "CLIENTS-" must be specified.
gate string OPTIONAL, server to adjust "clients_max" parameter on

The following options are acceptable:

  • "main" - for Main Gate server
  • "session" - for Session Gate server
  • "management" - for Management Gate server
 With no "gate" parameter specified, "clients_max" parameter of each of represanting i2Rest Gate servers will be adjusted.
number integer OPTIONAL, value to increase/decrease "clients_max" parameter
 1

CLIENTS API example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer VKys2XfGTeykM1m62767KvvJuHLgkhNp_-74LXtaLsc
Content-Length: 49
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"CLIENTS+",
	"gate":"main"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 68
Connection: keep-alive

{
  "status": "OK",
  "details": "CLIENTS+/- command was accepted"
}

WORKER+/- API

This API allows you to adjust amount of "worker" threads on each of representing i2Rest Gate servers. WORKER+ API call will increase amount of "worker" threads by specified number, WORKER- API call will decrease amount of "worker" threads by specified number.

WORKER+/- API parameters

To call WORKER+/- API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "WORKER+" or "WORKER-" must be specified.
gate string OPTIONAL, server to adjust worker threads amount on
number integer OPTIONAL, number of threads to add/remove
 1

WORKER+/- example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer nWYo_kp-UxMLjnEMhZp7yv6EUA-jNdEg66pz54woSDA
Content-Length: 24
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"WORKER+"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 72
Connection: keep-alive

{
  "status": "OK",
  "details": "Add worker(s) command was submitted"
}

ANONYMOUS+ API

This API submits anonymous session.

ANONYMOUS+ API parameters

To call ANONYMOUS+ API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "ANONYMOUS+" must be specified.

ANONYMOUS+ example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer nWYo_kp-UxMLjnEMhZp7yv6EUA-jNdEg66pz54woSDA
Content-Length: 27
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"ANONYMOUS+"
}

Response: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 137
Connection: keep-alive

{
  "status": "OK",
  "details": "Session started",
  "session": "8df78002-124d-1a49-ab93-0004ac19a205",
  "job": "068154/BTPL/I2RESTA"
}

STOP API

This API stops server instance.

STOP API parameters

To call STOP API, you must send POST request with following JSON object as request body (media type 'application/json'):

Field Type Description Default value
command string REQUIRED, "STOP" must be specified.

STOP example

Request: 

POST https://192.168.0.233:8080/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer YMtT6i4HpItTm171L-PVWj9PPPtICznxJWeuhrHT_KA
Content-Length: 21
Host: 192.168.0.233:8080
Connection: Keep-Alive

{
	"command":"STOP"
}

Responce: 

HTTP/1.1 200 OK
Server: i2Rest/1.0
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 62
Connection: close

{
  "status": "OK",
  "details": "Stop command was accepted"
}

Back to i2Rest API

Retrieved from "https://www.i2rest.com/index.php?title=Management_APIs&oldid=1959"