Menu
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 API Express. Find Part 1: REST APIs here, and Part 3: Comparison here.
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.
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.”
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, many companies continue to adopt it, thanks to its voluminous documentation history (SOAP predates REST by two years, and gained a lot of steam right away, before REST eventually overtook it), highly evolved security measures (such as with WS-Security), and strong built-in standardization (through its Envelope, Headers, Body, and error-handling).
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.” This WS-[protocol] standard is incredibly valuable for its extensibility, as it helps further define standards for specific communication requirements and scenarios.
Finally, SOAP messaging has the benefit of built-in error handling, through its element, which provides error details. The error information can then be parsed, and used within your RPG programs, as shown here.
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.
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.
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, wsdl2rpg to form a SOAP request, and SQL + HTTPPOSTCLOB + RPG in order to accomplish various database parsing operations. 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.
One of the easiest ways to create SOAP web services in RPG is with RPG API Express. 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:
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.
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.
To start creating SOAP APIs with RPG API Express, please look into our documentation site’s sample programs. For example, this page and this one 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.
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.