Skip to main content  
        iSeries home   |   Easy400  
Public-Source
 
Introduction
 
Client side
 Server side
 
 Download
 
 

 
ez4WebServ
IBM i WEB Services
Server side
1- The REST technique   4- Getting started
2- Our RESTful solution   5- Server security
3- Examples   6- References
If you need to develop some Web services on IBM i and you never did such a thing before, you should not be worried. You do not need IBM Websphere Application System (WAS), you do not need IBM Integrated Web Services (IWS), you do not have to know Java, you do not have to be an expert of all the intricacies of the Simple Object Access Protocol (SOAP) and its related Web Services Description Language (WSDL).
If you are just familiar with HTTP directives, if you are an ILE-RPG programmer and you have used CGIDEV2 to create Web CGI programs, just read this page and you will soon be done.



1- The REST technique

  1. REST requires the URL - requesting a WEB service - to be ...
    1. ... in the following format:
      http://ip_address:port_number/part1/part2/part3/.../partn
      where
      • part1 is a character string identifying the web servicing engine (some king of a dispatcher program, in charge for assigning requests to servicing programs)
      • part2 is a character string identifying the specific service to be invoked (example: CUST_LIST could mean that the request should be served by a a servicing program for customers listing)
      • part3 to partn are optional positional parameter values to be used by the final servicing program.
      Example:
      http://www.easy400.net:8018/ez4web/cust_list/italy/milan
      In this case, a basic engine program (identified by ez4web) will call a servicing program (identified by cust_list). This program will list all the customer in country 'italy' and city 'milan'. The parameter position tells if its value is related to the country or to the city.
    2. ... OR in the following format:
      http://ip_address:port_number/part1/part2?Query_string
      Example:
      http://ip_address:port_number/part1/part2?country=italy&city=milan
      In this case the parameters (variables) input to the servicing program are not positional. They belong to the "query string"
      ?country=italy&city=milan
      and are identified by a variable name (country, city). Their positions are not relevant, the query string could very well be
      ?city=milan&country=italy
  2. REST requires the servicing programs to provide as response a XML document. Something like this:
    <CUSTFILE>
      <CUSTRCD>
        <CUSTNBR>1473;/CUSTNBR>
        <CUSTNAME>John Brown</CUSTNAME>
        <CUSTCITY>Milan</CUSTCITY>
        <CUSTCTRY>Italy</CUSTCTRY>
      </CUSTRCD>
      <CUSTRCD>
        <CUSTNBR>2825;/CUSTNBR>
        <CUSTNAME>Tom Dooley</CUSTNAME>
        <CUSTCITY>Milan</CUSTCITY>
        <CUSTCTRY>Italy</CUSTCTRY>
      </CUSTRCD>
    </CUSTFILE>


 

2- Our RESTful solution is built as follow.

  • A. Special HTTP directive
    For Web servicing we set up a separate HTTP instance with the following directive:
    ScriptAliasMatch /ez4web/(.*) /qsys.lib/ez4webserv.lib/service.pgm
    In this way, any SCRIPT_NAME beginning with /ez4web/ causes the execution of program EZ4WEBSERV/SERVICE, the root servicing program.
  • B. The root servicing program finds out the program responsible for providing the response, then it calls it.
    • To find the final servicing program, the root program compares the second segment of the SCRIPT-NAME against the entries of a table (a database file named SRVTAB).
    • A CGI program is available to maintain the entries of the table. You invoke it with the URL:
      http://address:8018/ez4srvtab/
      The screen looks as follow:
      Figure 1 - Maintaining service table SRVTAB
      In this example, if the second segment of the SCRIPT_NAME contains cust-inq, the final servicing program EZ4WEBSERV/SERVICE01 is called.
  • C. The final servicing program
    • If the case, gets its parameters from segments of the SCRIPT-NAME environment variable
    • Sends its output - usually an XML script to the client [the client could very well be, for test purposes, a web browser]
    • Returns to the root servicing program.


 

3- Examples
EZ4WEBSERV includes two examples, covering both the client and the server sides.

  • The client programs are very simple, they just execute command URLGET.
  • The servicing programs
    • Load the external XML template (written according to CGIDEV 2rules)
    • Get the input parameters (variables)
    • Read database records according to the input parameters
    • Provide the XML output calling CGIDEV2 procedures updhtmlvar and wrtsection.
Read the sources of these programs to learn how to develop your own programs.
  1. The first example is run from command CALL EZ4WEBSERV/CLIENT01:
    1. Program CLIENT01 executes command
      EZ4WEBSERV/URLGET URL('http://www.easy400.net:8018/ez4web/cust_inq/1473/')
         STMF('/tmp/WebClient01Data.xml') STMFCCSID(1208) DSPSTMF(*YES)

      (if you install EZ4WEBSERV you may run this command from the command entry screen)
    2. site www.easy400.net is contacted via Scott Klement's HTTPAPI
    3. the appropriate directive of HTTP instance EZ4WEBSERV invokes the root servicing program EZ4WEBSERV/SERVICE
    4. the root servicing program EZ4WEBSERV/SERVICE checks the service table VRTSAV and calls the final servicing program EZ4WEBSERV/SERVICE01.
    5. the final servicing program EZ4WEBSERV/SERVICE01 gets the customer number 1473 from the environment variable and returns to the client an XML document containing information about that customer
    6. HTTPAPI receives the document, converts it to UTF-8 (CCSID 1208) and files it in a stream file of the client system
    7. client program CLIENT01 displays the document received.
  2. The second example is run from command CALL EZ4WEBSERV/CLIENT02:
    1. Program CLIENT02 executes command
      EZ4WEBSERV/URLGET
         URL('http://www.easy400.net:8018/ez4web/cust_list?Country=italy&city=milan')
         STMF('/tmp/WebClient01Data.xml') STMFCCSID(1208) DSPSTMF(*YES)

      (if you install EZ4WEBSERV you may run this command from the command entry screen)
    2. site www.easy400.net is contacted via Scott Klement's HTTPAPI
    3. the appropriate directive of HTTP instance EZ4WEBSERV invokes the root servicing program EZ4WEBSERV/SERVICE
    4. the root servicing program EZ4WEBSERV/SERVICE checks the service table VRTSAV and calls the final servicing program EZ4WEBSERV/SERVICE02.
    5. the final servicing program EZ4WEBSERV/SERVICE02 return to the client an XML document containing information on all customers
    6. HTTPAPI receives the document, converts it to UTF-8 (CCSID 1208) and files it in a stream file of the client system
    7. client program CLIENT02 displays the document received
    8. client program CLIENT02 executes command XMLPARSE/SUPERPARSE to upload the XML document data to a database file.
 First exampleSecond example
Command from your client system call ez4webserv/client01 call ez4webserv/client02
Run from the browser http://www.easy400.net:8018/
/ez4web/cust_inq/1473/
http://www.easy400.net:8018/
/ez4web/cust_list?country=italy&city=milan
Client program
 source code
CLIENT01 CLIENT02
Final servicing program
 source code
SERVICE01 SERVICE02
XML external script template /ez4webserv/xml_templates/template01.txt
XML document returned /tmp/WebClient01Data.xml /tmp/WebClient02Data.xml
Figure 2 - Code excerpts


 

4- Getting started

  1. Check the prerequisites
  2. Download the EZ4WEBSERV zip file
  3. Read and follow the installation instructions
  4. Start the EZ4WEBSERV http instance for the server side: use command
    STRTCPSVR SERVER(*HTTP) HTTPSVR(EZ4WEBSERV)
    (the instance listens on port 8018)
  5. Validate the installation by running command call ez4webserv/client01
  6. From your web browser access the Service Table with URL http://yourTcpAddress:8018/ez4srvtab/
  7. Add a new service. Example:
    Service ID:myservice
    Description:my first service
    Servicing program:MYSERVICE
    library:mylib
    (of course, your program MYSERVICE does not have to be already available)
  8. Develop your MYSERVICE program as if it were a regular CGIDEV2-based CGI program:
    • it must return something, a text page, a HTML page, a XML script
    • as external script you may use the XML template /ez4webserv/xml_templates/template01.txt
      Look at EZ4WEBSERV/QRPGLESRC mbr SERVICE01 as an example.
  9. Test your MYSERVICE program from your web browser with the URL
    http://yourTcpAddress:8018/ez4web/myservice/
  10. Get client service by entering the following command in the Command Entry screen of your IBMi:
    EZ4WEBSERV/URLGET URL('http://yourTcpAddress:8018/ez4web/myservice/')
    STMF('/tmp/myserviceData') DSPSTMF(*YES)
After succeeding in this, you'll have no limits.


 

5- Server security
To validate user access to the server, you may use HTTP directives based on user profiles or on validation lists. We do not discuss the user profile one, as you do not want outside people use your internal user profiles.

  1. To create a validation list
    • CRTVLDL VLDL(vldl_lib/vldl_name) AUT(*EXCLUDE)
    • GRTOBJAUT OBJ(vldl_lib/vldl_name) OBJTYPE(*VLDL) USER(QTMHHTTP QTMHHTP1) AUT(*USE)
  2. To maintain validation list entries, either you use the HTTP instance *ADMIN,
    OR you use the Easy400.net utility WRKVLDL.
  3. You need at least one validation list to validate the access to the Service Table. To implement protection for the Service Table, you may add the following directives to the EZ4WEBSERV HTTP instance:
    <LocationMatch (^/ez4srvtab/(.*)$)>
    AuthType Basic
    AuthName "EASY400 Web Services Config"
    PasswdFile vldl_lib/vldl_name1
    UserID user_profile_name1
    Require valid-user
    </LocationMatch>

    where:
    • vldl_lib/vldl_name1 is THE validation dedicated to protection of the Service Table
    • user_profile_name1 is the name of a user profile authorized to *CHANGE file EZ4WEBRDTA/SRVTAB (your Service Table).
      Note that user profiles QTMHHTTP and QTMHHTP1 must be authorized to *USE this user profile.
  4. The number of validation lists to validate access to the web services depends on the granularity of your services.
    For instance,
    1. if you want to protect all your Web services through a single validation list, you may use the following HTTP directives:
      <LocationMatch (^/ez4srv/(.*)$)>
      AuthType Basic
      AuthName "xxx Web Services"
      PasswdFile vldl_lib/vldl_name_x
      UserID user_profile_name_x
      Require valid-user
      </LocationMatch>

      where:
      • vldl_lib/vldl_name2 is the validation dedicated to protection of all the incoming Web service requests (it is higly tecommended to use a validation list different from the one used to protect the Service Table!)
      • user_profile_name2 is the name of a user profile authorized to access all the files involved in your Web services.
    2. if you want to protect all your Web service requests starting by /ez4srv/cust through a given validation list named vldl_lib/vldl_namey,
      you may use the following HTTP directives:
      <LocationMatch (^/ez4srv/cust(.*)$)>
      AuthType Basic
      AuthName "yyy Web Services"
      PasswdFile vldl_lib/vldl_name_y
      UserID user_profile_name_y
      Require valid-user
      </LocationMatch>



6- References
Some papers, articles and presentations about Web services with IBM i:

December 2008 - Daniel L. Hiebert, Nadir Amra: Getting Started With the Integrated Web-Services Server
April 2009 - Daniel L. Hiebert, Nadir Amra: Integrated Web Services With ILE Programs
February 2012 - Jon Paris, Susan Gantner: Need a REST? Building REST Web Services With RPG
2012 - 2016 - Scott Klement: Providing RPG Web Services on IBM i - Scott Klement
May2015 - IBM Corporation: Building a REST service with integrated web services server for IBM i: Part 1
May2015 - IBM Corporation: Building a REST service with integrated web services server for IBM i: Part 2
August2016 - IBM Corporation: Integrated Web Services ServerAdministration and Programming Guide
August2016 - IBM Corporation: Web Services Client for ILEProgramming Guide