Introduction

For several years now, IBM i users have had the ability to deploy ILE programs and services programs as web services based on the SOAP protocol using the integrated web services server support that is part of the operating system. REST web services were not supported by the integrated web services server, until the publishing of this article.

This article is the second in a series of articles about the integrated web services server REST support. Future articles in this series will build upon the basic concepts:

  • Part one starts out by explaining the basic concepts behind REST web services and how the integrated web services server supports REST services.
  • Part two takes you through the steps of deploying a simple ILE application as a RESTful web service.
  • Part three takes you through the steps of deploying a more complex ILE application that uses more of the REST features.

Prerequisites

Software

In order to get all the PTFs required by the integrated web services server in support of REST, you need to load the latest HTTP group PTF. Table 1 lists the HTTP group PTFs that are needed for each of the supported releases of the IBM i operating system.

Table 1. Software prerequisites
IBM i release HTTP Group PTF
IBM i 7.2 SF99713 (level 6 or greater)
IBM i 7.1 SF99368 (level 32 or greater)

Assumptions

Before reading this article, you should have read Part one of the article in the series in order to have a basic understanding of REST principles and the terminology used.
You can find links to various information on REST in the Resources section. You should also be familiar with the fundamental concepts of JavaScript Object Notation (JSON) and XML.

A simple RESTful application

The example we will use in this discussion is an application written in ILE RPG that converts the temperature from Fahrenheit to Celsius. The application is packaged within the service program QIWSSAMPLE in the library, QSYSDIR. This service program is included as part of integrated web services server support and contains one exported procedure, CONVERTTEMP.

You can find the source (see Listing 1) for the procedure at the following path:
/QIBM/ProdData/OS/WebServices/samples/server/ConvertTemp/CNVRTTMP.RPGLE

Listing 1. RPG source for simple REST application



h nomain PGMINFO(∗PCML:∗MODULE)
d ConvertTemp     pr
d tempIn                  10      const
d tempOut                 10

p ConvertTemp     b                   export
d ConvertTemp     pi 
d tempIn                  10      const 
d tempOut                 10

d tempI           s       8P   2
d tempO           s       8P   2
d value           S       50A
 /free
 value = %STR(%ADDR(tempIn));
 tempI=%DEC(value:7:2);
 tempO = (5/9)∗(tempI ‑ 32);
 value = %CHAR(tempO);
 tempOut = value;
 %STR(%ADDR(tempOut):10)=tempOut;
 /end‑free
 p ConvertTemp   e 


The RESTful web service to be deployed is very simple. The only thing that is needed by the application is the temperature that is to be converted from Fahrenheit to Celsius. And what is returned is the temperature in Celsius.

Things to get done before deployment

It is always a good idea to sit down and figure out things before actually deploying a RESTful web service. When deploying a RESTful web service, you should have answers to the following questions at the bare minimum:

  • What HTTP methods will the resource support?
  • How do I want the URIs to look like?
  • What incoming content types should be supported?
  • What type of data should be returned?

Let us quickly go through these basic questions in the context of the simple application that will be deployed.

What HTTP methods will the resource support?

The supported HTTP methods are GET, POST, PUT, and DELETE. Which HTTP methods you choose to support will affect how a client will send data. For example, if we wanted a resource method to receive XML or JSON documents, then we would probably bind the resource method to either the POST or PUT HTTP methods.

For the simple application that we will be deploying, the only input that is expected is the temperature that is to be converted, and this can be handled by having the client pass in the temperature as part of the URL. So there is no payload that a client needs to send, and thus the HTTP method will be GET.

Because we have only one procedure (resource method), we are done.

How do I want the URIs to look like?

REST services are based on manipulating resources. Resources for RESTful services are addressable, and URLs are the primary way of achieving addressability in REST. The design of REST URIs is an art in itself and beyond the scope of this article. What I will say is simplicity and consistency is the key.

For the temperature conversion example, we want the URI to look as follows:
<context-root>/ftoc/{temp}

Where, {temp} is the temperature in Fahrenheit that is to be converted to Celsius. For example, if we want to know the temperature of 123 Fahrenheit in Celsius, the URI that would be sent by a client would be as follows:
/web/services/ftoc/123

Note: The above URI assumes that the default context root (/web/services) was not changed for the server.

What incoming content types should be supported?

Because there is no payload with the HTTP GET request, we really do not care what the incoming content type is. In our example, we left the default, and that is to accept all content types.

What type of data should be returned?

We have three choices. We can return XML, JSON, or both depending on what the client is willing to accept. In this example, we will return JSON.

Now, we are ready to deploy the simple application as a RESTful web service.

Step 1. Create the integrated web services server

To deploy an ILE program object as a REST service, you need to have an integrated web services server created, and it must be version 2.6 or greater. If you have one already created, you can skip this section and go to the ” Step 2. Deploy the ILE application as a RESTful web service” section.

Nothing has changed as far as the steps to create an integrated web services server. The server can contain both SOAP and REST web services.

To launch the web services server wizard, you need to sign on to the IBM Web Administration for i GUI and click the Create Web Services Server wizard link. Point your browser to the Web Admin GUI for IBM i by specifying the following URL: ‘http://hostname:2001/HTTPAdmin‘, where hostname is the host name of your server (note that if SSL has been configured for the web administration server, the URL would be ‘https://hostname:2010/HTTPAdmin‘) and sign on. You must have the ALLOBJ and IOSYSCFG special authorities to create a web services server, or, if you are on an IBM i 6.1 or newer release, you must have been given the permission to create web services servers. Launch the Create Web Services Server wizard by either clicking the link in the navigation bar under the Common Tasks and Wizards heading, or on the main page of the Setup tab (see Figure 1).

Figure 1. Links to Create Web Services Server
alt

Step 1-1. Specify web services server name

You have the option of naming (see Figure 2) the web services server that is to be created. You can also provide a short description if you so choose.

Figure 2. Specify web services server name
alt

Accept the default values and click Next at the bottom of the form.

Step 1-2. Specify server user ID

Specify the user ID to run the jobs associated with the server. You have the option of specifying an existing user ID, creating a new user ID, or using the default user ID. We will use the default user ID, QWSERVICE.

Note: Any user ID specified for the server must be enabled and the password set to a value other than *NONE. Ensure this is true for the specified user ID.

Figure 3. Specify web services server name
alt

Click Next at the bottom of the form.

Step 1-3. Summary

The wizard shows you a summary page (see Figure 4), giving you the chance to see the details relating to the web services server before it actually begins the task of creating the server.

Figure 4. Server creation summary
alt

Clicking Finish at the bottom of the summary page begins the creation of the server. After the server is created, the wizard will start the web services server and the HTTP server. So if all goes well, you will eventually see the server in the Running state and the deployed services (a sample web service that is included with the server) active (with a green dot to the left of the service name) as shown in Figure 5.

Figure 5. Server running
alt

Congratulations, you have now successfully created a web services server. The next steps will guide you through deploying your first ILE program object as a RESTful web service.

Step 2. Deploy the ILE application as a RESTful web service

The following table summarizes the various details of the RESTful web service that we will be deploying:

Table 2. REST information for RESTful web service
Procedure CONVERTTEMP
URI ../ftoc/{temp}
HTTP method GET
Query string ignored
Request body ignored
Response code 200 OK
Response body JSON

As we go through the panels, you will see New panel alert! to indicate that the panel is new or has been updated as part of the REST web services support. So, let us get started.

Step 2-1. Deploy an IBM i program object as a web service

Click the Deploy New Service wizard link that is located in the navigation bar. See the panel in Figure 6.

Figure 6. Deploy web service – step 1
alt

New panel alert! This new panel gives you the option to either deploy a SOAP or REST web service. Because we are deploying a REST web service, we have selected the REST option.

Click Next to continue.

Step 2-2. Specify location of IBM i program object

We now need to specify (see Figure 7) an ILE program object name from which the web service is generated. There are two ways to locate the program object on the system. The default way is to specify the program and library names by selecting the Specify IBM i library and ILE object name (Recommended) option. Another way is to search for the program object by browsing the integrated file system (IFS), which could take a while if a directory that contains a lot of objects, such as /QSYS.LIB, is specified.

Figure 7. Deploy web service – step 2
alt

Enter qsysdir as the library name and qiwssample as the ILE object name and click Next.

Step 2-3. Specify a name for the resource (web service)

New panel alert! Now we need to give the web service (that is, the resource) a meaningful service name and description. By default, the service name and description is set to the name of the selected program object (see Figure 8).

Figure 8. Deploy web service – step 3
alt

The resource name has been changed to ftoc. In addition, you have the ability to set a URI path template for the resource. For this example, we have specified a URI path template for the resource that has a variable named tempand a regular expression that limits the value that can be specified for the variable to digits. This matches what we wanted the URI to look like, which is of the following form:
../ftoc/{temp}
Click Next to continue.

Step 2-4. Select the export procedures to externalize as resource methods

The wizard shows a list of exported procedures (as shown in Figure 9). For service programs (object type of *SRVPGM), there might be one or more procedures. For programs (object type of *PGM), there is only one procedure, which is the main entry point to the program. Expanding the procedure row shows the parameters for the procedure and various parameter attributes.

Figure 9. Deploy web service – step 4
alt

The parameter attributes are modifiable. In most cases, you want to modify the parameter attributes to control what data is to be sent by web service clients and what data is to be returned in the responses to the client requests.

In this example, the TEMPIN parameter is an input parameter, and the TEMPOUT parameter is the output parameter. This means that a web service client will need to only pass data corresponding to the TEMPIN parameter, and the response to the client request will be returned in the TEMPOUT parameter.

Click Next to continue.

Step 2-5. Specify resource method information

New panel alert! This panel (as shown in Figure 10) is used to specify various REST attributes on a per procedure basis.

Figure 10. Deploy web service – step 5
alt

The first two lines are the procedure name and URI path template for the resource, respectively. We have chosen to bind the resource method (that is, the procedure) to the HTTP request method of GET. We did not specify a URI path template for the resource method and thus *NONE is specified. We do not care about the content type of incoming requests, and so we specify *ALL.

The REST web service will return JSON data, so we specify JSON. There are no output parameters that will contain HTTP header data or the HTTP response code, so we specify *NONE for those fields.

Finally, we have chosen to unwrap the parameters so that we can inject a value into the parameter TEMPIN from a value in the URI. We specify the URI path template variable tempthat was defined in the URI path template for the resource.

Step 2-6. Specify user ID for this service

We now need to specify the user ID that the service will run under. As shown in Figure 11, you can run the service under the server’s user ID or you can specify an existing user ID that the service will run under.

Figure 11. Deploy web service – step 6
alt

In order for the web service to run correctly, the user ID status must be set to *ENABLED and the password must be set to a value other than *NONE. If a user ID is specified that is disabled or has a password of *NONE, a warning message is displayed and the service might not run correctly. In addition, ensure that the specified user ID has the proper authorities to any resources and objects that the program object needs, such as libraries, databases, and files.

In this example, we will accept the default. Click Next to continue.

Step 2-7. Specify library list

Specify any libraries that the program object needs to function properly (see Figure 12).

Figure 12. Deploy web service – step 7
alt

Fig12.JPG

You have the option of putting the libraries at the start of the user portion of the library list or at the end of the user portion of the library list. Click Next to continue.

Step 2-8. Specify transport information to be passed

Specify what transport information related to the client request is to be passed to the web service implementation code (see Figure 13). The information is passed as environment variables.

Figure 13. Deploy web service – step 8
alt

The transport metadata REMOTE_ADDR is passed to the web service implementation code in an environment variable named REMOTE_ADDR.

HTTP headers indicate what transport headers (for example, HTTP headers) to pass to the web service implementation code. Transport headers are passed as environment variables. The environment variable name for HTTP headers is made up of the specified HTTP header prefixed with ‘HTTP_‘, all in upper case. For example, if ‘Content-type' is specified, then the environment variable name would be ‘HTTP_CONTENT-TYPE'. If an HTTP header was not passed in on the web service request, the environment variable value will be set to the null string.

Click Next to continue.

Step 2-9. Deploy web service – step 9

The web service deployment wizard shows you a summary page (see Figure 14), giving you a chance to see the details relating to the web service being deployed.

Figure 14. Deploy web service – step 9 (Summary)
alt

On the Services tab, you can see information about the service being deployed.

If you click the Method tab, you can see the resource methods that correspond to the procedures that were selected to be deployed (see Figure 15).

Figure 15. Deploy web service – step 9 (Method tab)
alt

If you click the Request Information tab, you will see the transport information to be passed to the web service implementation code (see Figure 16).

Figure 16. Deploy web service – step 9 (Request Information tab)
alt

Clicking the Finish button at the bottom of the Summary page begins the installation process. When the web service is deployed, the deployed service becomes active (with a green dot to the left of service name) as in Figure 17:

Figure 17. Successfully deployed RESTful web service
alt

Congratulations, you have now successfully deployed your first ILE program object as a RESTful web service.

Unlike SOAP, there is no test client provided by the IBM Web Administration GUI to test the REST service. However, because the web service that we deployed has a resource method that is bound to the HTTP GET request method, we can use any browser to quickly test the service (for services that use other HTTP request methods, an external tool, such as SoapUI, must be used.). Figure 18 shows the result of the request.

Figure 18. Testing web service
alt

Summary

In Part one of this series, you learned the basic concepts behind REST web services and how the integrated web services server supports REST services. In this article, you learned how to deploy a simple ILE application as a RESTful web service.

Part three will take you through the steps of deploying a more complex ILE application that uses more of the REST features.

Resources