People sitting around REST API illustration

REST vs SOAP Architecture in RPG, Part 1: REST APIs

Which is right for your IBM i?

REST vs SOAP APIs: which is the right one for your API development architecture? Conventional wisdom says REST thanks to its ubiquity, and for many of us, it’s the first type of HTTP communication we’ve heard about. In fact, for most companies, REST is the best infrastructure to adopt, thanks to a variety of reasons, such as its simplicity, ease of use, versatility, and speed. However, the important thing to note here is that one architectural style isn’t “better” than the other; it’s just different. This is the first article in a three-part series that explores the practical differences between REST vs SOAP APIs, when to use them, and how to use them with RPG-XML Suite. Find Part 2: SOAP APIs here, and Part 3: Comparison here.

Icons showing basic uses of REST APIs in RPG

Definitions

The realm of client-server communication is loaded with acronyms and terms to keep track of. To begin with, let’s elaborate upon several key terms, and what they mean.

  1. REST – Representational State Transfer – REST is an architectural style, rather than a protocol (protocols define how diverse modules interact, while styles define how sets of protocols are organized[1]). REST utilizes existing web protocols and tools to communicate with APIs.
  2. SOAP – Simple Object Access Protocol – SOAP is a data-centric protocol that uses WSDL files for client-consumer communication.
  3. API – Application Programming Interface – An API is a system which allows two resources to connect or interface with each other. Think of it as similar to a restaurant waiter that facilitates transactions between a customer and the kitchen.
  4. Web Service – Web services, also known as Web APIs, are just that: services which enable two resources to communicate with each other over a web protocol.
  5. HTTP(S) – Hypertext Transfer Protocol (Secure) – HTTP(S), also simply known as HTTP, is a very popular document-centric transport protocol used when communicating between a client and web server. The (S) in its name stands for secure, which implements a transport layer of security (called TLS, formerly SSL) to send messages.
  6. XML – Extensible Markup Language – XML is a widely used data format, similarly structured to HTML. XML can be used in both SOAP and REST API calls.
  7. WSDL – Web Service Definition Language – WSDL is an XML-based notation used for describing functionality of a SOAP-based web service[2]. WSDL is used at development time to describe a web service program with procedure names, input/output parameters, the URL of the web service, and the enveloping mechanisms and transport to be used (i.e., SOAP over HTTP).
  8. JSON – JavaScript Object Notation – SON is arguably the fastest-growing data format used when communicating over HTTP in the present day, thanks to its memory-efficient format.
  9. RPG – Report Program Generator – RPG is the primary language used when developing business applications on the IBM i OS. Also known as RPG Free, RPGLE, and formerly RPG IV.
  10. IBM i – International Business Machines Integrated – IBM i is the operating system used on IBM’s POWER servers. IBM i is the OS name, which was formerly i5/OS and OS/400. AS/400 is what was renamed to iSeries, System i, and then Power.

Table of Contents

REST API Communication

An expanded definition

To define what a REST API really is, let’s start with IBM’s description of it: “REST APIs provide a flexible, lightweight way to integrate applications, and have emerged as the most common method for connecting components in microservices architectures.” [3] When IBM states that REST APIs are used to integrate applications, think of it as a way to say that REST APIs help facilitate the exchange of information (especially JSON & XML) between clients, resources, and the servers those resources are hosted on. 

As noted by IBM, REST APIs are widely used; in fact, they are the most common client-to-server API architecture being adopted in the world today. To further illustrate, when comparing REST vs SOAP (SOAP being the second most popular), IBM states, “Some APIs, such as SOAP … impose a strict framework on developers. But REST APIs can be developed using virtually any programming language and support a variety of data formats.” [4]

Now that we have a description of REST, let’s aim to define it. As stated in the Definitions section above, REST stands for Representational State Transfer. But what do these terms individually mean? Jamie Juvelier at HubSpot (a company whose public APIs use REST [5]) states it beautifully, “when a client requests a resource using a REST API, the server transfers back the current state of the resource in a standardized representation … In other words, REST APIs work by fielding requests for a resource and returning all relevant information about the resource, translated into a format that clients can easily interpret (this format is determined by the API receiving requests).” [6]

Who uses REST APIs?

One could argue that REST APIs are the de facto standard for web API development on the IBM i platform today. Companies everywhere are developing means to generate APIs, with some even specializing in converting SOAP APIs to REST APIs. DreamFactory presents an interesting case for why Fortune 500 companies have an impetus to modernize, and convert their applications to the newer, more agile development paradigm. [7

To elaborate further on Fortune 500 companies, Wal-Mart adopted a REST-centric testing methodology when adopting IBM’s CICS Asynchronous API. Part of the rationale behind adopting a REST-based testing methodology is thanks to the sheer availability and low price point that comes with REST development. REST was ideal for this project, as it could be used for both individual and multiple-client testing. [8, Page 65]

What are its benefits?

REST-centered API design can help businesses accomplish a variety of system-efficient goals. When compared to SOAP APIs, REST APIs discard the need for an envelope (a means of carrying a SOAP message), and are not bound to a specific data format, having access to many lightweight options, especially JSON; this can vastly reduce how many system resources an API consumes. For an overview of SOAP web service requirements, please look into part two of this series.

Another benefit of REST web services is that they are platform and language-independent (it is transport-dependent though, and requires HTTP). REST pulls from multiple different sources, and inherits traits from the platforms it uses. To that end, while REST is not secure by itself, it can inherit robust security measures by building on top of HTTPS.

Building web APIs with REST-centered design in mind is generally easier than with SOAP. As REST is designed to be human-readable, and also less verbose (via JSON), it helps developers understand what they are reading, faster, while also making it easier to produce. As stated by SOAPUI (a tool for building SOAP web services), “REST is easier to use for the most part and is more flexible[9].”

Tools & Resources for REST APIs

Having a suite of tools helps drastically reduce development time when building REST APIs. When connecting to a new API, assisting new customers with a proof of concept, or prototyping a new web service, our development team uses a variety of tools to accomplish programming goals. We recommend tools like these in order to help your own development.

  1. PostmanBy and large, Postman is one of the most valuable tools to use when testing new web services. Its well-designed “Collections” sidebar helps developers quickly access the projects that need to be tested, while its main interface provides a comprehensive dashboard of options to use when testing an HTTP request. [10]
  2. OpenAPIWhen creating documentation for a REST API, OpenAPI (known as OAS3 and formerly Swagger) helps expedite the process. As mentioned on their website, Swagger states “Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.” [11]
  3. RPG, JSON, and REST: How to Test IBM i Web ServicesThis blog post takes a deep dive into testing REST web services. It provides a series of examples on how to test GET and POST requests using both Postman and RPG-XML Suite. [12]
  4. Architectural Styles and the Design of Network-based Software ArchitecturesWhile more practical to scholars, this is Roy Fielding’s original dissertation on the principles of REST; this is the paper that helped shift the entire API paradigm towards a REST-centric one. [13]

What does a REST API workflow look like?

REST API workflows are typically comprised of a 3-step process, which we describe as the “Compose – Transmit – Parse” workflow when calling an API, and as the “Parse – Compose – Transmit” workflow when offering an API for consumption.

In a REST workflow, the “Compose” step consists of a few different requirements. First, the JSON being created needs to be well-formed so as to not cause processing errors down the line (note, JSON is not a requirement for REST; however it is the most widely used data format for it. We discuss the “Compose” step using XML in Part 2 of this series). This will require you to assemble the JSON with correct opening and closing brackets for objects (with curly brackets { }) and arrays (with square brackets [ ]). You will also need to specify any data types you want the JSON to represent, and correct key:value pairs for each data type.

The “Transmit” step functions in two segments – first, your IBM i sends a REST request containing various pieces of necessary information based on your HTTP Method verb. This will involve calling a target URI, and sending headers, request body information, query parameters, and other information. In the second segment, the URI your IBM i just called sends information back to your system. “Transmit” wraps the entire call-response action into one step.

After receiving information back from the target resource, your program will then parse the returned JSON. The “Parse” step typically involves extracting the JSON into program variables, DB2, or the IFS.

Offering an API is very similar to the previously mentioned steps here, except with the order rearranged. Initially, your program will be listening for incoming requests. When a resource sends your IBM i a REST request, your program will parse the information, compose a response based on the information you just received, and send back a response.

Hybrid Approach

A hybridized approach to developing REST-oriented architecture on your IBM i will typically involve a patchwork of open source and proprietary software. Following the same type of workflow mentioned above, a hybridized approach spreads out to use multiple options. To create JSON in document format, IBM provides the DATA-GEN tool [14]. To offer web services, IBM includes IWS, or Integrated Web Services as a proprietary service [15]. To parse JSON, one might use Scott Klement’s tool YAJL [16]. Open source software benefits from community engagement and free pricing, at the cost of dedicated support and a unified and standardized toolkit of RPG subprocedures for development.

Using 100% RPG

One of the easiest ways to create REST APIs in RPG is with RPG-XML Suite. RXS enables you to perform all commonly needed actions in REST web service communication, helping you establish a web service foundation capable of tackling problems head on – from basic to complex, RXS equips you with tools to heighten your development potential. With it, you can both call and offer web APIs over HTTP. RXS leverages commonly used aspects of REST web service architecture, such as transporting JSON (and XML); utilizing HTTP Method verbs like POST, GET, PUT/PATCH, and DELETE; headers to transport meta-data; and target URLs for resource calls.

Composing / Creating JSON, when calling or offering REST web services, will typically involve this kit of composition subprocedure APIs. Rather than covering both JSON and XML here, this section will only cover composing JSON, while the “Using 100% RPG” section in our other blog post in this series covers composing XML:

  1. Subprocedures
    1. RXS_CreateJson() – Used to begin JSON composition; creates a “root” for the JSON structure.
    2. RXS_FormatJson() – Used when formatting JSON; includes functions like minification and spacing.
    3. RXS_DestroyJson() – Used to finish JSON composition and clear memory; required.
    4. RXS_ComposeJsonArray() – Adds a JSON array to a parent JSON Object or Array.
    5. RXS_ComposeJsonObject() – Adds a JSON object element to a parent JSON Object or Array.
    6. RXS_ComposeJsonNumber() – Adds a JSON number element to a parent JSON Object or Array.
    7. RXS_ComposeJsonBoolean() – Adds a JSON boolean element to a parent JSON Object or Array.
    8. RXS_ComposeJsonNull() – Adds a JSON null element to a parent JSON Object or Array.
    9. RXS_ComposeJsonString() – Adds a JSON string element to a parent JSON Object or Array.
    10. RXS_GetJsonString() – Retrieves composed JSON from RXS_CreateJson() subprocedure.
    11. RXS_GetJsonStringLen() – Calculates length of composed JSON from RXS_CreateJson() subprocedure.

Rather than covering both calling and offering web services here, this section focuses on the latter, while the second post in this series includes a list of the tools required when calling web APIs. Transmitting JSON & XML via REST to callers involves using the robust PutStdOutDS data structure associated with the RXS_PutStdOut() subprocedure. RXS_PutStdOut()’s versatility allows it to send information used with HTTP calls, allowing it to easily communicate with both REST & SOAP web services.
 
  1. Subprocedures (offering)
    1. RXS_GetEnvVar() – Retrieves an Apache environment variable or an incoming HTTP header.
    2. RXS_PutEnvVar() – Sets or modifies a job-level environment variable.
    3. RXS_GetStdIn() – Reads data from an HTTP POST request via Standard In.
    4. RXS_PutStdOut() – Outputs data to Standard Out (such as a client calling your IBM i).
    5. RXS_GetUrlVar() – Parse a URL path or querystring for a specified name/value pair.
  2. Tools (offering)
    1. CRTRXSSVR – Allows the user to create an HTTP server instance for use by RPG-XML Suite.
    2. HTTP – Command for performing various HTTP server action.
    3. RXSRTR – Creates enhanced functionality between your HTTP server and CGI program.
    4. CRTRXSRTRE – Allows the user to create a new environment for use with the RXS Router.
    5. WRKRXSRTRE – Allows the user to work with configuration entries used with the RXS Router.
    6. INZRXSRTR – Initializes the RXS Router cache to include current pointer values.


Parsing JSON and XML with RXS is a breeze. When utilized alongside our parsing generator tool, developers will only need to use one RXS subprocedure along with their generated parsing code.

  1. Tools
    1. BLDPRS – Used to aid in writing RPG-XML Suite JSON or XML parsing code.
  2. Subprocedures
    1. RXS_ParseJson() – Subprocedure used for SAX (event-based) parsing of JSON documents.
    2. RXS_Parse() – Subprocedure used for SAX (event-based) parsing of XML documents. Look into the second post in this series for a more in-depth view into using XML when parsing.


To start creating REST APIs with RPG-XML Suite, please look into our documentation site’s sample programs. For example, this page [17] shows an example program on how to create XML, while this one [18] shows how to transmit an HTTP GET request and parse the response using event-based parsing. We recommend looking into these pages for advanced tutorials on composing [19] and parsing [20] JSON.

Conclusion​

In the REST vs SOAP debate, most companies will find that REST is a perfectly suitable design philosophy to adopt when sending data across HTTP, thanks to its versatility, lightweight format, ease of use.

For a table of REST API vs SOAP API benefits, look into the third post in this series.

Try RXS free for 30 Days

Want to try RPG-XML Suite for yourself? Try it free for 30+ days with a proof of concept.

A proof of concept is designed to help you save time when developing REST APIs by providing a solution for your new development goals. For example, a proof of concept can give you a complete “Compose – Transmit – Parse” workflow program in RPG. All you would need to do is send us a brief description of your program requirements, along with any available API documentation.

Proof of concept turnarounds are fast, and capable of solving the needs of most RPG + API developers. Our team has the expert knowledge to craft your program quickly, and provide you a solution well before your due dates. To develop REST web services in RPG, or to try any of RPG-XML Suite’s tools, reach out to us, and we will answer any questions we can.

References