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 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 API Express. Find Part 2: SOAP 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.
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.” 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.”
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) 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).”
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.
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.
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.”
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.
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.
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. To offer web services, IBM includes IWS, or Integrated Web Services as a proprietary service. To parse JSON, one might use Scott Klement’s tool YAJL. 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 REST APIs in RPG is with RPG API Express. RPG API Express 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, it equips you with tools to heighten your development potential. With it, you can both call and offer web APIs over HTTP. RPG API Express 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:
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.
To start creating REST APIs with RPG API Express, please look into our documentation site’s sample programs. For example, this page shows an example program on how to create XML, while this one 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 and parsing JSON.
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.