Menu
Every day, RPG shops use REST IBM i web services to communicate with their clients. However, their software options are often limited to open source tools written in C or Java, with even fewer solutions available in RPG. What’s worse is that of the options available, only a handful can compose, transmit, and parse web service data in a single package of RPG subprocedures… there’s a fix for that – and that’s where RPG API Express comes in.
RPG API Express is a web API toolkit containing dozens of subprocedures and utilities to help RPG developers with everyday tasks. In other words, it lets you compose and parse XML & JSON, and transmit SOAP & REST web service data. Furthermore, RPG API Express clears common web service hurdles, such as encoding, CCSID conversion, encryption, and text-conversion. Read below to see what RPG API Express can do.
IBM i (or AS400/ iSeries) REST web services are everywhere these days. As such, this article will highlight RPG API Express’s commonly used REST features, and will parallel these features using the Postman web service testing tool. Overall, this blog post:
To begin, restful is an extension of the acronym REST, which itself stands for REpresentational State Transfer. In this context, “REST” is a set of rules or standards used when following HTTP/HTTPS protocols. By following a REST architecture, programs can transmit text, XML, and JSON data to an API endpoint (a communication touchpoint between an API and a server), and get a response back in turn.
Servers communicate with REST web services via four HTTP methods: POST, GET, PUT/PATCH, and DELETE, with GET and POST being the most common. These methods strongly parallel the so-called CRUD operations used in relational database applications. Note the CRUD operations below, which create, read, update, or delete a resource’s data, as well as their HTTP counterparts.
Of those mentioned, this post focuses specifically on GET and POST HTTP Methods. Typically, GET requests are used to gather information in a read-only fashion. POST requests, on the other hand, are used when sending sensitive information, like passwords or authorization keys.
While most web services use REST APIs, many will use another protocol instead: SOAP, which stands for Simple Object Access Protocol. Some differences between the two are that SOAP:
REST, on the other hand:
With that in mind, neither REST nor SOAP is strictly “better” than the other. However, covering both is beyond the scope of this article. If you are interested in offering or consuming RPG SOAP web services on your IBM i, go to the RPG API Express documentation site for more info.
Each HTTP Method has its own rules. For example, making an HTTP GET request requires two particular pieces of information, and an optional third:
The first piece, or Request Method, describes how information is requested, while the second piece, or Target URL, describes where it’s being requested from. The optional third piece, or Query String Parameter, tells the web service what a request is looking for by passing in parameters formed as “key=value” pairs.
This article will use Postman, a free API testing tool, to make GET and POST requests. The team over at Postman has included some great documentation on making REST HTTP requests here.
In this example, Postman is making a GET request to the Target URL:
https://postman-echo.com/get?foo1=bar1&foo2=bar2
The image below includes the Query String Parameters foo1=bar1 and foo2=bar2:
After sending the request parameters, the API at postman-echo.com sends back a response body. This body contains JSON objects such as the query string parameters (“args”), default header information (“headers”), and Target URL (“url”), as shown below:
You can make RPG GET requests by using RPG API Express’s RXS_Transmit() subprocedure. Other than standard program code (declarations, control-options, etc), these three lines accomplish the same task as in Postman:
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_GET;
TransmitDS.URI = 'https://postman-echo.com/get?foo1=bar1&foo2=bar2';
Response = RXS_Transmit( *Omit : TransmitDS );
To explain, line 1 declares the HTTP Request Method, while line 2 declares the Target URL and Query String Parameters. Line 3 assigns response JSON from the RXS_Transmit() call to the Response variable.
It’s really that easy. RPG API Express’s web service subprocedures are all built into one convenient toolkit, saving you from the time and stress that comes with being an RPG web service developer. RPG API Express simplifies your RPGLE REST web service infrastructure. If you have a business need in mind, contact the RPG API Express sales team here for a free proof of concept.
With a proof of concept, the RPG API Express development team builds out a program based on your use case. This can cover a wide range of scenarios, such as:
Along with the proof of concept, you will get a free trial license of RPG API Express for 30 days or longer, depending on your needs. Drop the team a line and see how RXS can help you.
When working with REST IBM i web services, it’s common to need more than just a GET request to fetch data. Users may need POST requests too when updating resources. The examples below describe some common POST requirements.
Like a GET request, POST requests require an HTTP Request Method and Target URL. However, unlike a GET request, a POST request typically does not include Query String Parameters, and includes a Request Body instead.
A POST Request Body often includes a special “Content-Type” header describing its format. This header tells the client server what data is being sent and how to interpret it. Some of the most common Content-Type headers used in restful web services include:
The first and default Content-Type header, application/x-www-form-urlencoded, is similar to the Query String Parameters sent in a GET request. However, instead of being sent through the URL, the Query String Parameters are sent through a Request Body. The application/json header specifies that JSON request data is being sent (though not in a file format). The third common header, multipart/form-data, is used when sending large amounts of binary data, files like PDFs or CSVs, and non-ASCII files.
As it is one of the most common Content-Type headers, this first example of sending a POST request will use the application/x-www-form-urlencoded header.
To create the test request within Postman, first specify the HTTP Request Method and Target URL in the request bar. Next, select the x-www-form-urlencoded Content-Type header as shown below. Finally, make sure to include the “foo:bar” key:value pairs:
After clicking the “Send” button, Postman makes the POST request and gets a JSON-formatted Response Body back. Notice below that unlike the GET request, the “args” object echoed back is now empty. Furthermore, instead of being specified as a Query String Parameter, the parameters are now being specified in a “form” object. Also, note that the Content-Type header on line 15 is specified in the “content-type” object. Finally, note the echoed JSON from the postman-echo.com endpoint.
The RPG API Express code required to perform the Postman equivalent of an application/x-www-form-urlencoded HTTP request is relatively simple. Program declarations aside, these steps show how to create a similar call:
URLEncodeDS.EncodeDecode = RXS_ENCODE;
bar1Encoded = RXS_Convert( %Trim( bar1 ) : URLEncodeDS );
bar2Encoded = RXS_Convert( %Trim( bar2 ) : URLEncodeDS );
Request = 'foo1=' + %Trim( bar1Encoded )
+ '&foo2=' + %Trim( bar2Encoded );
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_POST;
TransmitDS.URI = 'https://postman-echo.com/post';
TransmitDS.HeaderContentType = 'application/x-www-form-urlencoded';
Response = RXS_Transmit( Request : TransmitDS );
In this example code:
This next example shows how to send JSON along with the application/json Content-Type header. Assume the same Target URL is being called. To enter request data, first select “raw”, then “JSON” as shown below. From there, enter JSON data in the text editor.
After clicking the “Send” button, Postman echoes back JSON-formatted response data. Note that the “args” and “form” objects below are empty, while the “data” object is filled. This is because the Content-Type header application/json is being used instead to specify a raw JSON Body as its contents. Also notice the echoed response data sent back to Postman once again.
Program declarations aside, RPG API Express accomplishes the same application/json request as the Postman example above:
Request = '{"foo1":"bar1";"foo2":"bar2"}';
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_POST;
TransmitDS.URI = 'https://postman-echo.com/post';
TransmitDS.HeaderContentType = 'application/json';
Response = RXS_Transmit( Request : TransmitDS );
In this example code:
This last example involves transmitting a multipart/form-data Content-Type header along with a file, here named “jsonData.json”. Following below, select form-data, specify the key as “File”, name the Key, and select a file (you can create your own “jsonData.json” file first).
After clicking the “Send” button, Postman echoes back a JSON response. Notice that the “args”, “data”, and “form” objects below are all empty, while the “files” object contains information on the “jsonData.json” file. This is because a multipart/form-data Content-Type header was specified, which is often used to send files. Also, notice the empty (null) “json” object:
RPG API Express makes it easy to transmit files requiring the multipart/form-data Content-Type header. With declarations aside, the example below is of an RXS program transmitting an IFS JSON file via POST:
TransmitDS.RequestStmf = '/tmp/jsonData.json';
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_POST;
TransmitDS.URI = 'https://postman-echo.com/post';
TransmitDS.HeaderContentType = 'multipart/form-data';
TransmitDS.LogFile = '/tmp/transmitLog.txt';
RXS_Transmit( *Omit : TransmitDS );
In the example:
IBM i web services are crucial to the world’s digital infrastructure – businesses make HTTP calls every day by logging into websites, updating inventory, or ordering lunch. However, many RPG shops struggle to easily consume web services from their IBM i’s. It’s not that there aren’t options out there – the issue is that many of those options require a Java or C-based solution. Oftentimes, shops have to cobble together multiple non-RPG options to take care of their XML, JSON, SOAP, and REST needs.
That’s where RPG API Express comes in. Between the RXS_Transmit() subprocedure for consuming web services and the RXS Router utility for offering them, RPG API Express’s thoroughly documented toolkit helps you take care of all things web services in RPG.
RPG API Express has an established presence in the IBM i community, and you can try it with a free, no commitment proof of concept. After describing your business needs to us, the RXS development team can then build out your RPG API Express program and provide you with a trial license key. Click here and try out the industry’s top RPG web service toolkit.