Image featuring words such as API, and REST vs SOAP

REST vs SOAP Architecture in RPG, Part 3: Comparison

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 third 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 2: SOAP APIs here.

Icons showing basic difference in REST vs SOAP APIs

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 vs SOAP Comparison

While they are both useful for different reasons, when comparing REST vs SOAP, most businesses prefer to utilize REST-oriented architecture for HTTP communication with APIs. This is thanks especially to REST’s lightweight and flexible format, enabling programmers more agility in developing new API infrastructure. With that in mind, SOAP’s rigidly-defined standard helps alleviate its security risks.

REST SOAP
1
JSON, XML, CSV,
plain text, HTML, +
XML Only
2
Typically HTTP
HTTP, SMTP, and FTP
3
Several HTTP Methods
POST & GET Only
4
Lightweight
Resource Heavy
5
More Flexible
More Standardized
6
Architectural Style
Protocol
7
Inherits security measures
Defines its own security
8
Stateless
Stateful
9
More Human-Readable
Less Human-Readable

Table Source info includes [3].

Let’s do a quick overview of what each of these rows mean:

  1. While REST web services typically send JSON & XML data, it can send a variety of other data formats as well. SOAP, on the other hand, is restricted to sending XML.
  2. REST APIs use a variety of web standards and typically communicate over HTTP. SOAP on the other hand, can communicate over a variety of other protocols, such as HTTP, SMTP, and FTP.
  3. One of REST’s greatest advantages is that it can employ a variety of HTTP Methods, especially the CRUD-stylized ones (Create, Read, Update, Delete). REST can use POST, GET, PUT/PATCH, and DELETE. SOAP HTTP communication is restricted to POST and GET.
  4. REST’s greater flexibility allows it to use more lightweight data formats, such as JSON or plain text, while SOAP is restricted to using only XML. Furthermore, due to its envelope-style payload, SOAP messages are typically more resource heavy than REST calls. SOAP messages require more bandwidth than similar REST calls.
  5. REST’s flexibility is why 83% of APIs use it, compared to the 15% who use SOAP [4]. REST uses easy to understand, human-readable standards, lending it both a smaller learning curve and faster implementation. SOAP’s standards are what make it valuable in distributed enterprise environments, and it is language, platform, and transport independent [5].
  6. REST web services are an architectural style of HTTP communication, which adopts a variety of web standards, such as JSON, XML, URI, and HTTP. SOAP is a rigid, well-defined protocol that uses exclusive constraints.
  7. When comparing REST vs SOAP security, REST APIs inherit security measures from their underlying transport, while SOAP follows a set of pre-defined standards.
  8. Stateless vs. stateful: Stateless services rely on clients to maintain sessions and center around operations that manipulate resources, rather than the state. Stateful services keep track of sessions or transactions and react differently to the same inputs based on that history. [6]
  9. When comparing REST vs SOAP APIs, REST tends to be much more human-readable. REST requests are simply packaged, sometimes only requiring a request URL and HTTP Method; it might be transporting JSON, which is easier for people to read than XML. Conversely, SOAP messages always require an envelope to carry messages, and can only use the more verbose XML.

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. If neither REST nor SOAP are suitable for shuttling data to your business partners, you can always try the experimental method of “IP over Avian Carriers“. [7😉

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 or SOAP 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