I read this article (written by Scott Klement) a few years ago and it was a great intro to the principles of using a webservice to read data on another computer in the cloud. Fast forward to this week, and since I’ve just written a webservice control procedure, I was looking for this document to show a colleague. Sadly the demise of iProDeveloper meant the page had vanished from the cloud of interwebs but I managed to snaffle an old copy and thought it useful to revive it and re-publish. So, here it is – a great intro to JSON, YAJL and writing webservices in general. #thanksscott 🙂
Me mumbling and copy pasting
aka – Access data running on other computers with REST and JSON
Every organization has more than one computer. So it’s only natural that companies need a way for programs on one computer to call programs running on others. The server running the HR software, for example, might need to call the server running the sales software to determine how much commission to pay the company’s salespeople in a given month.
Over the years, the IT industry has developed many ways for programs to call other programs, but the best way I’ve found is web services. In this article, I’ll discuss how to write a Representational State Transfer (REST) web service in RPG that returns data in JavaScript Object Notation (JSON) format. As part of that discussion, I’ll introduce an open-source JSON tool known as Yet Another JSON Library (YAJL), which I’ve found to be indispensable.
The Case for REST and JSON
I prefer to use REST web services in the programs that I write for my organization because REST carries less overhead and requires fewer dependencies. On the other hand, if I were writing a web service for customers, vendors, or others outside my organization to use, I’d write it in Simple Object Access Protocol (SOAP). There are a ton of tools available to assist you with coding SOAP, and those tools obviate the need for me to teach large numbers of people how to use the web service. However, SOAP web services are more complicated to write because the tools add layers of complexity, and they come with overhead that slows the service. With SOAP there’s often an HTTP server, an application server, and a web services server, as well as my program. By contrast, REST just comes with the HTTP server and my program. Fewer layers of software mean less overhead!
Versatility is another advantage of REST. A SOAP web service sends its data in SOAP format, which is a type of XML. If I need to send JSON data (or other formats such as images, PDFs, Word documents, etc.), I encode the data first so that it can be embedded in an XML document. This also adds overhead to the web service. REST, however, lets you send data in any format, so I can send a raw image, PDF document, or whatever it is that I need to send. In this article, I’ll demonstrate how to send data in JSON format without having to encode it in an XML format (I couldn’t do that with SOAP).
JSON’s data format is similar to that of XML in many ways. Like XML, JSON lets you provide named data/value pairs and nest data inside of other data, and it’s a plain-text format. But that’s where the similarities end. JSON is lighter weight—it expresses the same data in fewer characters than XML.
In addition, JSON is always coded in UTF-8 (it doesn’t support other encodings), making it simpler to deal with—and you don’t have to worry about it sometimes being in ASCII or other flavors of Unicode and then having to deal with all those possibilities in your program, because you know it’s always UTF-8.
My favorite thing about JSON is that it’s a subset of JavaScript, in which it’s used as a way to initialize variables. As an analogy, RPG provides several ways to initialize data. To initialize stand-alone variables, RPG has D-spec’s INZ keyword. To initialize arrays or tables, it has compile-time data (the data you put beneath the ** line at the bottom of your program.) In JavaScript, however, you use JSON to initialize data, and that’s why I use JSON for web services that communicate with JavaScript programs—because JSON is easy to use from JavaScript, and it performs better than XML.
Yet Another JSON Library
YAJL is an open-source JSON generator and parser that was created by Lloyd Hilaiel, who works for Mozilla and, therefore, is—without a doubt—very familiar with browser technologies like JSON. YAJL provides two ways to parse JSON data, as well as the JSON generator that I demonstrate in this article. Why use YAJL instead of another JSON tool? Well, last year, a colleague and I at Profound Logic looked for the best JSON parser to use in our software. We needed something that would be fast, because our software is known for its high performance, and were worried that JSON parsing might slow it down. We investigated a dozen different JSON tools and found that YAJL was by far the most efficient. It was double the speed of the next fastest tool!
YAJL is written in C and designed to be called from C programs. However, I wrote an RPG front end to make it easy to use YAJL from RPG programs. You can get a copy of YAJL, my RPG front end, and the sample code demonstrated in this article from my website at scottklement.com/yajl.
Build a Web Service
To provide an example for this article, I’ve written a web service in RPG that retrieves stock status. You can request the status of an individual item in stock (or if no item is specified, the web service will return all items). The basic idea is that the caller provides a Uniform Resource Identifier (URI) in the format http://your-system.com:8500/stockqty /itemno, where “your-system.com:8500” is replaced by the IP address or domain name of the computer running the service and the port number of the HTTP server. The itemno portion of the URL is optional. If supplied, the service will provide only the stock status for that item; if it’s not provided, the service will provide stock status for all items.
Mainline of the STOCKQTY web service, written in RPG
monitor;
uri = getURI();
itempos = %scan('/stockqty/': uri) + %len('/stockqty/');
itemid = %subst(uri: itempos);
on-error;
itemid = *blanks;
endmon;
readData(itemid: data);
createJSON(data: jsonBuf);
sendReply(data.success: jsonBuf);
return;
Need to know more?
Modernization – From AS400 to ISERIES to IBM i on Power Systems
Learn the history of AS/400, the replacement iSeries machines and then to modern IBM POWER SYSTEMS. Internet connectivity is integral to modern eBusiness – Learn how to work with IBM i Webservices to create new interfaces and modernize old ones.