Example contents of envelope for SOAP API

REST vs SOAP Architecture in RPG, Part 2: SOAP 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 second 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 1: REST APIs here, and Part 3: Comparison here.

Icons showing basic uses of SOAP 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

SOAP Web Service Communication

An expanded definition

As described by IBM, SOAP (or Simple Object Access Protocol), 

is a lightweight protocol for the exchange of information in a decentralized, distributed environment. A SOAP message is a transmission of information from a sender to a receiver. SOAP messages can be combined to perform request/response patterns.

SOAP is transport-independent but is most commonly carried over HTTP in order to run with the existing Internet infrastructure. SOAP enables the binding and use of discovered web services by defining a message path for routing messages. [3]

Who uses SOAP APIs?

When comparing REST vs SOAP, new SOAP API development is rare to find these days, and is typically reserved for maintenance of enterprise systems. For example, if a multinational company has a deeply entrenched SOAP infrastructure that is still functioning, it may be more cost-efficient to maintain that same system, rather than adopt a new one. 

Even while SOAP has declined in popularity relative to REST [4], many companies continue to adopt it, thanks to its voluminous documentation history (SOAP predates REST by two years[5], and gained a lot of steam right away, before REST eventually overtook it), highly evolved security measures (such as with WS-Security [6]), and strong built-in standardization (through its Envelope, Headers, Body, and error-handling [7]).

What are its benefits?

When comparing SOAP vs REST, SOAP provides numerous advantages. 

Similar to REST, SOAP APIs are language and platform independent; that is, any language or platform can be built to accommodate SOAP architecture. One advantage SOAP has over REST is that it is transport-independent. While REST requires HTTP as its transport protocol, SOAP can run on top of a variety of protocols, such as HTTP, FTP, SMTP, and others.

To further elaborate, SOAP has the advantage of standardization in its implementations. Not only is it standardized in structure (as mentioned in the previous section via Envelopes, etc.), it is standardized by a set of protocols that typically begin with WS-[protocol]. One implementation of this standard is through WS-Security, which IBM says, “works across multiple transports and is independent of the underlying transport protocol.” [8] This WS-[protocol] standard is incredibly valuable for its extensibility, as it helps further define standards for specific communication requirements and scenarios. [9]

Finally, SOAP messaging has the benefit of built-in error handling, through its element, which provides error details. [10] The error information can then be parsed, and used within your RPG programs, as shown here. [11]

Tools & Resources for SOAP APIs

When building SOAP APIs, having a suite of tools helps drastically reduce your development time. 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. SoapUIWhile Postman (mentioned in the first post in this series) does have SOAP-handling functions, our team recommends SoapUI for this purpose instead. Its project-management capabilities, expansive documentation, and Endpoint Explorer tool all make for quicker testing and development. [12]
  2. SOAP, WSDL, HTTP, XSD? What the?Check out this article to learn more about the myriad of acronyms native to SOAP web services. It provides an in-depth look into what terms like SOAP, WSDL, XML, XSD, and HTTP mean. [13]
  3. How to use SoapUI + WSDL for XMLThis video tutorial covers the basics of how to use SOAPUI and a WSDL to generate sample request and response XML. [14]

What does a SOAP API workflow look like?

Similar to the REST example in our first post, SOAP web service 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 SOAP workflow, the “Compose” step consists of a few different requirements. First, the XML being sent in a SOAP envelope needs to adhere to the constraints as defined by a WSDL, as well as the typical SOAP requirements. This will require you to assemble the XML with various pieces of information in mind, such as the URI you are calling, the SOAP action, namespaces, body information, and header information.

The “Transmit” step functions in two segments – first, your IBM i sends the SOAP envelope containing all the information formed in the “Compose” step you’ve created to a target URI; second, that URI 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 XML. The “Parse” step typically involves extracting the XML 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 SOAP request, your program will parse the information, compose a response based on the information you just received, and send back a response.

Hybrid Approach

Similar to REST, SOAP API architecture deployed in RPG will often use a mix of open source software and IBM’s proprietary tools. To accomplish a full SOAP workflow involves stitching together multiple open source options into one single program. For example, one might use IBM’s DATA-GEN to create XML [15], wsdl2rpg to form a SOAP request [16], and SQL + HTTPPOSTCLOB + RPG in order to accomplish various database parsing operations [17]. 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 SOAP web services in RPG is with RPG-XML Suite. RXS enables you to perform all commonly needed actions in SOAP web service communication. With it, you can both call and offer APIs over HTTP using established standards such as WSDLs to define languages and XSDs for validating XML, as well as creation templates and parsing subprocedure generators for handling XML.

Composing / Creating Composing / Creating XML when calling or offering web services will typically involve these template composition tools and subprocedures:

  1. Tools
    1. BLDTPLAids in composing RPG-XML Suite templates, or *.tpl files; used alongside CRTRPGTPL.
    2. CRTRPGTPLCompiled source member template; uses *.tpl file to create template subprocedure.
  2. Subprocedures
    1. RXS_StartComposeEngine()Initializes the template composition engine with a template file.
    2. RXS_ComposeSection()Writes a named section to the composition engine buffer (a buffer is a region of memory or data area used to temporarily store data for a short amount of time for further processing).
    3. RXS_ComposeVariable() – Replaces the currently loaded template Variable with the Value parameter.
    4. RXS_GetComposeBuffer() – Retrieves the current composition engine buffer into a variable.
    5. RXS_GetComposeBufferLen() – Returns the current length of composed data in the buffer.

Transmitting XML over SOAP typically involves using the robust TransmitDS data structure associated with the RXS_Transmit() subprocedure. Offering SOAP web services typically involves using the same types of tools and RXS functions as described in the first blog post’s “Using 100% RPG” section.
 
  1. Subprocedures (calling)
    1. RXS_Transmit() – For communicating with remote web services.


Parsing 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. While RXS includes parsing with a set of DOM tools, most developers will benefit from the speed and time-saving benefits of SAX-style parsing.

  1. Tools
    1. BLDPRSUsed to aid in writing RPG-XML Suite XML or JSON parsing code.
  2. Subprocedures
    1. RXS_Parse()Sets up XML parsing; used along with the generated BLDPRS handler (a handler is a routine that deals with an event, allowing a programmer to write code that is executed when the event occurs).


To start creating SOAP APIs with RPG-XML Suite, please look into our documentation site’s sample programs. For example, this page [18] and this one [19] show example programs on how to create XML, transmit a SOAP-based request, and parse the response using SAX parsing handlers and the DOM parsing APIs. 

Conclusion

In the REST vs SOAP debate, while most companies will find that REST is a perfectly suitable design philosophy to adopt when sending data across HTTP, some may find that SOAP is more optimal due to heightened security measures and standardization.

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

Try RXS Free for 30 Days

One of the most beneficial aspects of a proof of concept is that we essentially build the frame on which your web services will operate; all you need to do is provide data to feed into it. 

For example, a proof of concept for a “Compose – Transmit – Parse” SOAP web service would be straightforward – you send us a WSDL containing the web service’s specifications, and we will build you all of the necessary RPG code to create XML, send it to a target URL, get a response, and parse the information.

It’s as easy as that! Get in touch with us, and describe what you would like to accomplish in your RPG + API development goals.

References

[1]—https://www.cds.caltech.edu/~doyle/wiki/index.php?title=Network_architecture_and_protocols

[2]—https://www.soapui.org/docs/soap-and-wsdl/working-with-wsdls/

[3]—https://www.ibm.com/docs/en/radfws/9.7?topic=applications-soap

[4]—https://trends.google.com/trends/explore?cat=5&date=all&geo=US&q=soap,rest

[5]—https://www.xml.com/pub/a/ws/2001/04/04/soap.html

[6]—https://www.ibm.com/docs/en/app-connect/11.0.0?topic=security-ws

[7]—https://www.altexsoft.com/blog/engineering/what-is-soap-formats-protocols-message-structure-and-how-soap-is-different-from-rest/

[8]—https://www.ibm.com/docs/en/bpm/8.5.6?topic=properties-ws-security-specification

[9]—https://www.infoq.com/articles/ws-standards-wcf-bustamante/

[10]—https://www.ibm.com/docs/en/integration-bus/10.0?topic=message-soap-fault

[11]—https://www.ibm.com/support/pages/access-soap-fault-rpg-stubs

[12]—https://www.soapui.org/learn/api/soap-vs-rest-api/

[13]—https://www.rpg-xml.com/soap-wsdl-http-xsd-what-the/

[14]—https://www.rpg-xml.com/generate-xml-in-soapui-using-a-wsdl/

[15]—https://www.ibm.com/docs/en/i/7.3?topic=codes-data-gen-generate-document-from-variable

[16]—http://www.tools400.de/English/Freeware/WSDL2RPG/wsdl2rpg.html

[17]—https://www.itjungle.com/2017/10/02/guru-consuming-rest-web-service-using-sql-post/

[18]—https://isupport.krengeltech.com/rxs/3.4/examples/celsius/

[19]—https://isupport.krengeltech.com/rxs/3.4/examples/celsiusdom/