|
|
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
- REST requires the URL - requesting a WEB service - to be ...
- ... 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.
- ... 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
- 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. After starting HTTP instance EZ4WEBSERV, youn may invoke it with the URL:
http://address:8018/ez4websrvp/wrksrvtab.pgm
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.
- The first example is run from command CALL EZ4WEBSERV/CLIENT01:
- 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)
- site www.easy400.net is contacted via Scott Klement's HTTPAPI
- the appropriate directive of HTTP instance EZ4WEBSERV invokes the root servicing program EZ4WEBSERV/SERVICE
- the root servicing program EZ4WEBSERV/SERVICE checks the service table VRTSAV and calls the final servicing program EZ4WEBSERV/SERVICE01.
- 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
- HTTPAPI receives the document, converts it to UTF-8 (CCSID 1208) and files it in a stream file of the client system
- client program CLIENT01 displays the document received.
- The second example is run from command CALL EZ4WEBSERV/CLIENT02:
- 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)
- site www.easy400.net is contacted via Scott Klement's HTTPAPI
- the appropriate directive of HTTP instance EZ4WEBSERV invokes the root servicing program EZ4WEBSERV/SERVICE
- the root servicing program EZ4WEBSERV/SERVICE checks the service table VRTSAV and calls the final servicing program EZ4WEBSERV/SERVICE02.
- the final servicing program EZ4WEBSERV/SERVICE02 return to the client an XML document containing information on all customers
- HTTPAPI receives the document, converts it to UTF-8 (CCSID 1208) and files it in a stream file of the client system
- client program CLIENT02 displays the document received
- client program CLIENT02 executes command XMLPARSE/SUPERPARSE to upload the XML document data to a database file.
4- Getting started
- Check the prerequisites
- Download the EZ4WEBSERV zip file
- Read and follow the installation instructions
- Start the EZ4WEBSERV http instance for the server side: use command
STRTCPSVR SERVER(*HTTP) HTTPSVR(EZ4WEBSERV)
(the instance listens on port 8018)
- Validate the installation by running command call ez4webserv/client01
- From your web browser access the Service Table with URL http://yourTcpAddress:8018/ez4srvtab/
- 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)
- 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.
- Test your MYSERVICE program from your web browser with the URL
http://yourTcpAddress:8018/ez4web/myservice/
- 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.
- 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)
- To maintain validation list entries, either you use the HTTP instance *ADMIN,
OR you use the Easy400.net utility WRKVLDL.
- 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.
- The number of validation lists to validate access to the web services depends on the granularity of your services.
For instance,
- 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.
- 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:
|
