Nowadays, web services have become an integral part of the IT world. They are used everywhere - even where you least expect it - and they make life a lot easier.

What are web services?

A web service can be defined as an application component interface. It is accessible via web protocols and allows you to use a client, (for instance an app or web application) to submit a request to a (web) service via the internet. They facilitate the interaction between different applications. The web service communicates by forwarding machine-readable file formats such as XML and JSON. This ensures communication compliance between different applications without the need to agree on separate rules for each connection between two applications. Web services are made available over a network, which makes a network connection essential.

Web services and IBM i

As important as web services have become today, IBM could not stay behind. It also supports web services on their IBM i servers. An IBM i server can communicate with web services via the internet, but can also offer web services by itself.

Web service requests

There are several ways to use your IBM i server to make web service requests. The first way is to call these services via SQL. If we want to use this method, the web service will be called via an SQL statement. The response will then be returned in a JSON or XML format. A variety of SQL functions can then be used to process this data.

This makes it fairly easy to test, because you can execute these SQL statements ahead of time, and you don't get to see them until you run the program you have processed them in.

A second option would be to use the Integrated Web Services Client. You can then request web services via various C procedures. You can populate the request string through an RPGLE program and handle the JSON or XML response in an SQL RPGLE one. Also use C procedures for error handling. You do need at least four different C procedures to make one web service call, and this can be a pitfall if you are not very familiar with C procedures.

The last method is to call web services via Java methods.

You can do this by writing your own Java programs. This framework will then handle the XML or JSON response. For easy access, write an RPG wrapper service program for the Java code. You can do this for any kind of web service, and it is especially useful if a specific option not already exists in the SQL functions.

Choose the technique you prefer based on your knowledge of the necessary programming language. Although, it is a best practice to use the SQL functions first. They are fast, and you get to see your results immediately, without having to write much code.

Offering web services

You can also use your IBM i server to offer web services.

Do this by using the Integrated Web Services Server on the IBM i server, or use the CGI (Common Gateway Interface).

Use IWS Soap web services and REST to set up APIs. This is done via a handy GUI wizard that guides you through all the steps needed to set up and deploy the service. The processing is then executed by an RPGLE service program or an SQL statement. JSON or XML is not needed in RPGLE or SQL, and the required request parameters can be directly linked to RPGLE or SQL parameters by using the wizard.

Via CGI both SOAP web services and REST, APIs can be configured. Processing is done via an RPGLE program. There is a wizard available for the HTTP server setup (to link a program to a resource). The complete JSON or XML request can be found in the RPGLE program.

Try to use the IWS first and only use the CGI if limitations do not allow IWS, the request/response is too complex or is not a JSON/XML, the WS client decides on the request/response and if you require detailed logging and error information.

New methods to request web services

Now, let me tell you about the new IBM i web services developments.

Previously, all requests were submitted via the Systools library. As of September 2021, new features have been introduced. They are included in the Qsys2 Library. These functions use http transport APIs instead of Java calls. They are more performant and have a more limited footprint.

These new features process SSL certificates differently and have system support for TLS encryption.

These new features use the default system certificate store, which does not exist by default. If you choose to have your application trust the JVM certificates, you can use an SQL script you will find in the documentation to copy the JVM trust store to the system one. Without this new trust store, it is not possible to execute HTTPS functions because you will not have the proper certificates. You will have to configure this trust store once for your IBM i server before you can use HTTPS functions without any issues, if you include the newly created trust store in these parameters.

You also have to pay attention to the order of the different parameters because it differs from the systools functions. Furthermore, you can easily solve this by clarifying which parameter this is e.g. URL => 'https://someurl.com', OPTIONS => {JSON-options}, REQUEST_DATA => 'data-in-JSON-format'. Using this notation allows you to immediately see which parameter is concerned, regardless of the order.

There are also a lot of different new header options. The header must always be in a JSON format, unlike the old HTTP functions, so you can no longer use an XML format for the header.