Difference between revisions of "Remote API call config"

From i2Rest
Jump to: navigation, search
 
(23 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
:Create DDM file on i2Rest Server IBM i using [https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_71/cl/crtddmf.htm CRTDDMF command].
 
:Create DDM file on i2Rest Server IBM i using [https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_71/cl/crtddmf.htm CRTDDMF command].
 
<pre>
 
<pre>
[QSYS/CRTDDMF FILE(QGPL/RMTSYS) RMTFILE(QGPL/RMTSYS) RMTLOCNAME(<target IBM i IP> *IP)                     
+
CRTDDMF FILE(QGPL/RMTSYS) RMTFILE(QGPL/RMTSYS) RMTLOCNAME(<target IBM i IP> *IP)                     
 
</pre>
 
</pre>
  
 
;Step 3
 
;Step 3
:Create text file named I2RESTECHO.PCML anywhere on target IBM i that will process remote API call 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:
+
: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:
 
<pre>
 
<pre>
 
<pcml version="1.0">
 
<pcml version="1.0">
Line 22: Line 22:
 
</pre>
 
</pre>
 
;Step 4
 
;Step 4
:Register two users on i2Rest server IBM i.
+
:Register two users on IBM i. The first will be used as a demonstrative OAuth2 resource owner, and the second one as an OAuth2 client.
 +
 
 
;Step 5
 
;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, user (must be a regestered IBM i user) and client (must be a regestered IBM i user) with appropriate values.  
+
: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). Сopy and paste the snippet bellow. Replace with appropriate values highlighted with <b>bold</b> parts: host_name, ports, pcml_file, system name, user (resource owner) and client.  
[[I2Rest_quick_config|Basic configuration]] remote API call variant (differences are highlighted in <span style="background:#e3f6d0;">green</span>):
+
[[I2Rest_quick_config|Basic configuration]] remote API call variant (differences are highlighted in <span style="background:#D3D3D3;">gray</span>):
 
   
 
   
  
Line 31: Line 32:
 
     "gates":
 
     "gates":
 
     {
 
     {
       "main"      : {"url":"http://<span style="color:red;"><host_name>[:port] (for example api.i2rest.com:1234)</span>"},
+
       "main"      : {"url":"http://'''<host_name>[:port] (for example api.i2rest.com:1234)'''"},
       "management" : {"url":"http://<span style="color:red;"><host_name>[:port] (for example api.i2rest.com:4321)</span>"},
+
       "management" : {"url":"http://'''<host_name>[:port] (for example api.i2rest.com:4321)'''"},
       "system"    : {"url":"http://<span style="color:red;"><host_name>[:port] (for example api.i2rest.com:4567)</span>"}
+
       "system"    : {"url":"http://'''<host_name>[:port] (for example api.i2rest.com:4567)'''"}
 
     },
 
     },
 
     "session_systems":
 
     "session_systems":
 
     [
 
     [
 
       {  "name"  : "*ANONYMOUS",  
 
       {  "name"  : "*ANONYMOUS",  
           "submit" : "SBMJOB JOB(I2RESTA)               \
+
           <span style="background:#D3D3D3;">"submit" : "SBMRMTCMD DDMFILE(QGPL/RMTSYS)
                            USER(${user})              \
+
                              CMD('SBMJOB CMD(CALL I2REST
                            CMD(CALL I2REST             \
+
                                              PARM(<nowiki>''-session''
                                PARM('-session'         \
+
                                                  ''-url'' ''${surl}''
                                    '-url' '${surl}'   \
+
                                                  ''-uid'' ''${uid}''
                                    '-uid' '${uid}'     \
+
                                                  ''-init' ''ADDLIBLE I2REST''</nowiki>))')"
                                    '-user' '${user}')) \
+
       },</span>
                            INLLIBL(I2REST)"
+
       <span style="background:#D3D3D3;">{  "name"  : '''<system name> (for example REMOTE)'''",
       },
 
       <span style="background:#e3f6d0;">{  "name"  : "<span style="color:red;"><system name> (for example REMOTE)</span>",
 
 
           "submit" : "SBMRMTCMD DDMFILE(QGPL/RMTSYS)
 
           "submit" : "SBMRMTCMD DDMFILE(QGPL/RMTSYS)
 
                               CMD('SBMJOB CMD(CALL I2REST
 
                               CMD('SBMJOB CMD(CALL I2REST
 
                                               PARM(<nowiki>''-session''
 
                                               PARM(<nowiki>''-session''
 
                                                   ''-url'' ''${surl}''
 
                                                   ''-url'' ''${surl}''
                                                   ''-uid'' ''${uid}''</nowiki>))')"
+
                                                   ''-uid'' ''${uid}''
                                 
+
                                                  ''-init' ''ADDLIBLE I2REST''</nowiki>))')"
 
       }</span>
 
       }</span>
 
     ],
 
     ],
Line 60: Line 59:
 
       {
 
       {
 
           "pcml_mount"        : "echo",
 
           "pcml_mount"        : "echo",
           "pcml_file"          : "<span style="color:red;"><complete name of i2restecho.pcml on IFS (for example /tmp/PCML/i2restecho.pcml)></span>",
+
           "pcml_file"          : "'''<complete name of i2restecho.pcml on IFS (for example /tmp/PCML/i2restecho.pcml)>'''"б
 
           "valid_in_anonymous" : true
 
           "valid_in_anonymous" : true
      }
 
 
     ],
 
     ],
     <span style="background:#e3f6d0;">"OAuth2":
+
     <span style="background:#D3D3D3;">"OAuth2":
 
     {
 
     {
 
       "scopes":
 
       "scopes":
 
       {
 
       {
 
           "run_program" : {"description":"Authorized API call"},
 
           "run_program" : {"description":"Authorized API call"},
           "system_<span style="color:red;"><system_name> (for example REMOTE)</span>" : {"description":"<span style="color:red;"><scope description></span>"},
+
           "system_'''<system_name> (for example REMOTE)'''" : {"description":"'''<scope description>'''"},
 
       },
 
       },
 
       "users":
 
       "users":
 
       {
 
       {
           "<span style="color:#22d3d3;">USRX</span>":{"description":"<span style="color:#22d3d3;">John Johnes</span>","valid_clients":{"<span style="color:#22d3d3;">TSTCLNT</span>":{"scopes":["run_program"]}}}
+
           "'''USRX'''":{"description":"'''John Johnes''',"valid_clients":{"'''TSTCLNT'''":{"scopes":["run_program"]}}}
 
       },
 
       },
 
       "clients":
 
       "clients":
 
       {
 
       {
           "<span style="color:#22d3d3;">TSTCLNT</span>":{"redirect_uri":"<span style="color:#22d3d3;"><main gate URL></span>/oauth2/redirect",  
+
           "'''TSTCLNT'''":{"redirect_uri":"'''<main gate URL>'''/oauth2/redirect",  
 
                     "description":"Test client",  
 
                     "description":"Test client",  
 
                     "valid_scopes":["run_program"],
 
                     "valid_scopes":["run_program"],
Line 85: Line 83:
 
     }</span>  
 
     }</span>  
 
  }
 
  }
Both "run_command" and "system_<system_name>" scopes must be specified obtaining OAuth2 token.
+
Both "run program" and "system_<system_name>" scopes must be specified obtaining OAuth2 token to perform authorized remote API call.<br>
 +
Anonymous remote sessions, that allows API call without OAuth2 token obtained, are also possible. SBMRMTCMD command must be defined under <code>*ANONYMOUS</code> session system to provide this feature (as it shown above).<br>
 +
Now you are ready to [[I2Rest_Start|start]] serving remote API call.<br/>

Latest revision as of 14:28, 9 July 2020

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 IBM i. The first will be used as a demonstrative OAuth2 resource owner, and the second one as an OAuth2 client.
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). Сopy and paste the snippet bellow. Replace with appropriate values highlighted with bold parts: host_name, ports, pcml_file, system name, user (resource owner) and client.

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

Both "run program" and "system_<system_name>" scopes must be specified obtaining OAuth2 token to perform authorized remote API call.
Anonymous remote sessions, that allows API call without OAuth2 token obtained, are also possible. SBMRMTCMD command must be defined under *ANONYMOUS session system to provide this feature (as it shown above).
Now you are ready to start serving remote API call.