i2Rest API

From i2Rest
Revision as of 15:45, 20 May 2020 by Pavel.lobko (talk | contribs) (→‎WORKER+/- example)
Jump to: navigation, search

i2Rest API

i2Rest Server provides a set of web services to call IBM i programs and commands, as well as APIs to manage i2Rest Server instance.

run_program API

This API allows you to call IBM i programs as Json REST web service. To call IBM i program, you must prepare file describing program parameters in PCML format, and publish this description to i2Rest Server.

It is required to obtain OAuth2 token with run_program scope to call IBM i programs. Token is not required on calls to programs which has "valid_in_anonymous":true flag in PCML.

run_program API URL

API run_program is available on Main Gate endpoint. The URL for run_program API of specific program is as follows: 

http[s]://<your_i2Rest_server>/run_program/<pcml_mount_point>/<pcml_program_name>

where:

  • your_i2Rest_server - host name and optional port of i2Rest Server instance (defined in Main Gate Config)
  • pcml_mount_point   - mount name where PCML file is deployed
  • pcml_program_name  - program name as defined in PCML file

example: 

https://i2rest.com/run_program/echo/echo

run_program API parameters

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

Field Type Description Default value
input object Input parameters object

The structure of input parameters depends on the program call definition described in appropriate PCML document. Non-passed parameters will be replaced with their default values

tracein boolean Trace input parameters

Boolean flag to specify the requirement to print input parameters in job log. If true, all input parameters will be printed in session job log before performing call to program

false
traceout boolean Trace output parameters

Boolean flag to specify the requirement to print output parameters in job log. If true, all output parameters will be printed in session job log after call to program

false
joblog boolean Return job log

Specifies whether to return session job log together with output parameters. If true, array with job log messages will be added to return parameters. Job log will contain messages arrived only during this program call. Use this flag only for debugging purposes. Producing of responses with job log can impact on performance

false
joblog_on_error boolean Return job log in case of errors

The same as previous, but job log messages will be returned only in case of errors. Still impact on performance, even when no error will occur

false

run_program example

Request: 

POST https://i2rest.com/run_program/echo/echo/

{
      "input": {"echo": "0"},
      "tracein": true,
      "joblog": true,
      "traceout": true
}

response: 

{
  "output": {
    "echo": "0"
  },
  "joblog": [
    "Input:",
    "echo (10):",
    "000000 :0               :F0 00 00 00 00 00 00 00   00 00",
    "Output:",
    "echo (10):",
    "000000 :0               :F0 00 00 00 00 00 00 00   00 00"
  ],
  "job": "030075/USRX/I2RESTA"
}

run_command API

This API allows you to call IBM i commands.

It is required to obtain OAuth2 token with run_command scope to call IBM i programs.

run_command API URL

API run_command is available on Main Gate endpoint. The URL for run_command API is as follows: 

http[s]://<your_i2Rest_server>/run_command

where:

  • your_i2Rest_server - host name and optional port of i2Rest Server instance (defined in Main Gate Config)

example: 

https://i2rest.com/run_command

run_command API parameters

To call run_command 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, Command to call

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

joblog boolean Return job log

Specifies whether to return session job log together with output parameters. If true, array with job log messages will be added to return parameters. Job log will contain messages arrived only during this program call. Use this flag only for debugging purposes. Producing of responses with job log can impact on performance

false
joblog_on_error boolean Return job log in case of errors

The same as previous, but job log messages will be returned only in case of errors. Still impact on performance, even when no error will occur

false

run_command example

Request: 

POST https://i2rest.com/run_command/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: Bearer Sv_y7kL0YHTXHyn-QCT5l1Y0QazLIyGqZniPmbLBnLQ
Content-Length: 66
Host: i2rest.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
     "command": "DSPLIBL OUTPUT(*PRINT)",
     "joblog": true
 }

response: 

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

{
  "status": "OK",
  "details": "Command call was completed successfully",
  "joblog": [
    "Printer device PRT01 not found. Output queue changed to QPRINT in library QGPL."
  ],
  "job": "030126/USRX/I2RESTS"
}

OAuth2 APIs

TODO

swagger

scope

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 i2Rest Server instance (defined in Management Gate Config)

example: 

https://192.168.0.233:8080


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

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

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

This API returns clients details.

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 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 of each of represanting i2Rest Gate servers will be dispayed.

CLIENTS 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_SWAGGER

GET_SWAGGER API parameters

To call GET_SWAGGER 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_SWAGGER" 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

PCMLS API

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

Request: 

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

DEBUG

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
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+/-

WORKER+/-

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 one, WORKER- API call will decrease amount of "worker" threads by one.

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

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, each of represanting i2Rest Gate servers will be affected.

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+

This API starts 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

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"
}

Response: 

HTTP/1.1 400 Bad Request
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"
}
Retrieved from "https://www.i2rest.com/index.php?title=I2Rest_API&oldid=683"