How to call API located on remote IBM i server

I2Rest Server can perform call to a program located on another IBM i server (for shortness and clarity hereinafter in this page IBM i with i2Rest Server started on it will be referred as i2Rest Server IBM i, IBM i with a located on it program to be called remotly will be referred as target IBM i).

Step 1

Install i2Rest on the target IBM i.

Step 2

Create DDM file on i2Rest Server IBM i using CRTDDMF command.

CRTDDMF FILE(QGPL/RMTSYS) RMTFILE(QGPL/RMTSYS) RMTLOCNAME(<target IBM i IP> *IP)                     

Step 3

Create text file named I2RESTECHO.PCML anywhere on target IBM i IFS, for example "/tmp/PCML/i2restecho.pcml". Copy and paste following code. It represents a description for the sample program I2RESTECHO, that is included into i2Rest Server installation for demonstration purposes:

<pcml version="1.0">

   <program name="echo" path="/QSYS.LIB/%LIBL%.LIB/I2RESTECHO.PGM">
      <data name="echo" usage="inputoutput" type="char" length="10" trim="both"/>
   </program>

</pcml>

Step 4

Register two users on i2Rest Server IBM i.

Step 5

Contact your system administrator for your i2Rest Server IBM i server host name (or IP) and two available ports for "main" and "management" gates of your first i2Rest Server instance. Create file config.json (you can name it with any name and put it into any available IFS folder). Enter following text, replace host_name, ports, pcml_file, system name, user (must be a regestered IBM i user) and client (must be a regestered IBM i user) with appropriate values.

Basic configuration remote API call variant (differences are highlighted in gray):

{
   "gates":
   {
      "main"       : {"url":"http://<host_name>[:port] (for example api.i2rest.com:1234)"},
      "management" : {"url":"http://<host_name>[:port] (for example api.i2rest.com:4321)"},
      "system"     : {"url":"http://<host_name>[:port] (for example api.i2rest.com:4567)"}
   },
   "session_systems":
   [
      {  "name"   : "*ANONYMOUS", 
         "submit" : "SBMRMTCMD DDMFILE(QGPL/RMTSYS)
                              CMD('SBMJOB CMD(CALL I2REST
                                             PARM(''-session''
                                                   ''-url'' ''${surl}''
                                                   ''-uid'' ''${uid}''
                                                   ''-init' ''ADDLIBLE I2REST''))')"
      },
      {  "name"   : <system name> (for example REMOTE)",
         "submit" : "SBMRMTCMD DDMFILE(QGPL/RMTSYS)
                              CMD('SBMJOB CMD(CALL I2REST
                                             PARM(''-session''
                                                   ''-url'' ''${surl}''
                                                   ''-uid'' ''${uid}''
                                                   ''-init' ''ADDLIBLE I2REST''))')"
      }
   ],
   "pcmls":
   [
      {
         "pcml_mount"         : "echo",
         "pcml_file"          : "<complete name of i2restecho.pcml on IFS (for example /tmp/PCML/i2restecho.pcml)>"б
         "valid_in_anonymous" : true
   ],
   "OAuth2":
   {
      "scopes":
      {
         "run_program" : {"description":"Authorized API call"},
         "system_<system_name> (for example REMOTE)" : {"description":"<scope description>"},
      },
      "users":
      {
         "USRX":{"description":"John Johnes,"valid_clients":{"TSTCLNT":{"scopes":["run_program"]}}}
      },
      "clients":
      {
         "TSTCLNT":{"redirect_uri":"<main gate URL>/oauth2/redirect", 
                   "description":"Test client", 
                   "valid_scopes":["run_program"],
                   "valid_grant_types":["authorization_code"]}
      },
      "tokens": {"type":"token"},"codes":{"type":"code"}
   } 
}

"system_<system_name>" scopes must be specified obtaining OAuth2 token to perform request.
Please, take a look on *ANONYMOUS session system. Anonymous sessions are possible only for the * ANONYMOUS system. If the SBMRMTCMD command will be registered on this system, then you do not need to get run_program