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
streamed_response	boolean	Serialize output parameters on the fly This parameter can improve i2Rest Server performance. By default, Server processes output PLIST and creates temporary JSON object in memory. After that, it serializes this JSON object and sends response to client. This PLIST pre-processing allows to analyze assert conditions before sending response to client With "streamed_response":true, server starts sending service response immediately when it starts processing of output PLIST. This reduces the cost of preparing a response message and improves system performance. From other side, if assert condition will be met somewhere in between of output processing, the response will contain two parts - incomplete "output" object and "errors" object. Warning! "streamed_response":true changes HTTP Transfer-Encoding in the response to "chunked", and removes Content-Length parameter. The server will return a 200 status code even if it encounters an assert condition while processing the output PLIST.	false
unsafe_heap	boolean	Use unsafe heap storage for program parameters By default, i2Rest Server session uses safe heap to allocate parameters passed to RPGLE programs. This ensures that discrepancies in pcml definitions and real program parameters will not lead to a violation of the session memory. If the program tries to access memory outside of the allocated memory, an error message will be generated With "unsafe_heap":true, session will allocate memory for parameters in its own heap. Such operation can be slightly faster then allocating in the safe heap. You can use this setting only if you guarantee that PCML and program parameters are consistent.	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"
}

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. Here is a full list of all API provided:

• STATUS API
• GET_OPENAPI30 API
• DEBUG API
• PCMLS API
• ADD_PCML API
• DEL_PCML API
• CLIENTS API
• CLIENTS+/- API
• SESSIONS API
• ANONYMOUS+ API
• WORKER+/- API
• STOP API