Comparing RESTful APIs and SOAP APIs Using MuleSoft as an Example

Simple Object Access Protocol (SOAP) and Representational State Transfer (REST) are two answers to the same question: how to access web services. The choice initially may seem easy, but at times it can be surprisingly difficult.

SOAP is a standards-based web services access protocol that has been around for a while and enjoys all of the benefits of long-term use. Originally developed by Microsoft, SOAP really isn’t as simple as the acronym would suggest.

REST is the newcomer to the block. It seeks to fix the problems with SOAP and provide a truly simple method of accessing Web services. However, sometimes SOAP is actually easier to use; sometimes REST has problems of its own. Both techniques have issues to consider when deciding which protocol to use.

Before I go any further, it’s important to clarify that while both SOAP and REST share similarities over the HTTP protocol, SOAP is a more rigid set of messaging patterns than REST. The rules in SOAP are important because, without these rules, you can’t achieve any level of standardization. REST as an architecture style does not require processing and is naturally more flexible. Both SOAP and REST rely on well-established rules that everyone has agreed to abide by in the interest of exchanging information.

A Quick Overview of SOAP

SOAP relies exclusively on XML to provide messaging services. Microsoft originally developed SOAP to take the place of older technologies that don’t work well on the Internet such as the Distributed Component Object Model (DCOM) and Common Object Request Broker Architecture (CORBA). These technologies fail because they rely on binary messaging; the XML messaging that SOAP employs works better over the Internet.

After an initial release, Microsoft submitted SOAP to the Internet Engineering Task Force (IETF) where it was standardized. SOAP is designed to support expansion, so it has all sorts of other acronyms and abbreviations associated with it, such as WS-Addressing, WS-Policy, WS-Security, WS-Federation, WS-ReliableMessaging, WS-Coordination, WS-AtomicTransaction, and WS-RemotePortlets. In fact, you can find a whole laundry list of these standards on Web Services Standards.

The point is that SOAP is highly extensible, but you only use the pieces you need for a particular task. For example, when using a public Web service that’s freely available to everyone, you really don’t have much need for WS-Security.

The XML used to make requests and receive responses in SOAP can become extremely complex. In some programming languages, you need to build those requests manually, which becomes problematic because SOAP is intolerant of errors. However, other languages can use shortcuts that SOAP provides; that can help you reduce the effort required to create the request and to parse the response. In fact, when working with .NET languages, you never even see the XML.

Part of the magic is the Web Services Description Language (WSDL). This is another file that’s associated with SOAP. It provides a definition of how the web service works, so that when you create a reference to it, the IDE can completely automate the process. So, the difficulty of using SOAP depends to a large degree on the language you use.

One of the most important SOAP features is built-in error handling. If there’s a problem with your request, the response contains error information that you can use to fix the problem. Given that you might not own the Web service, this particular feature is extremely important; otherwise you would be left guessing as to why things didn’t work. The error reporting even provides standardized codes so that it’s possible to automate some error handling tasks in your code.

An interesting SOAP feature is that you don’t necessarily have to use it with the HyperText Transfer Protocol (HTTP) transport. There’s an actual specification for using SOAP over Simple Mail Transfer Protocol (SMTP) and there isn’t any reason you can’t use it over other transports. In fact, developers in some languages, such as Python and PHP, are doing just that.

A Quick Overview of REST

Many developers found SOAP cumbersome and hard to use. For example, working with SOAP in JavaScript means writing a ton of code to perform extremely simple tasks because you must create the required XML structure absolutely every time.

REST provides a lighter weight alternative. Instead of using XML to make a request, REST relies on a simple URL in many cases. In some situations, you must provide additional information in special ways, but most Web services using REST rely exclusively on obtaining the needed information using the URL approach. REST can use four different HTTP 1.1 verbs (GET, POST, PUT, and DELETE) to perform tasks.

Unlike SOAP, REST doesn’t have to use XML to provide the response. You can find REST-based Web services that output the data in Command Separated Value (CSV), JavaScript Object Notation (JSON) and Really Simple Syndication (RSS). The point is that you can obtain the output you need in a form that’s easy to parse within the language you need for your application.

As an example of working with REST, you could create a URL for Weather Underground. The API’s documentation page shows an example URL of http://api.wunderground.com/api/Your_Key/conditions/q/CA/San_Francisco.json. The information you receive in return is a JSON formatted document containing the weather for San Francisco. You can use your browser to interact with the Web service, which makes it a lot easier to create the right URL and verify the output you need to parse with your application.

REST API Examples

This topic describes the following examples of consuming REST APIs:

• Simple Example: Consuming a REST API that shows how to retrieve data from a REST API
• Extracting XML Data from a REST API and inserting it in an External DB
•  A JSON to Object Transformer example, showing how to consume a REST API and insert selected data into an external database        

Simple Example: Consuming a REST API

This is fully functional example designed for quick and effortless setup and testing. It queries the Bacon Ipsum REST API, which generates Lorem_ipsum text, and is convenient because it does not require HTTPS or setting up an account to use. The example consists of only one flow, shown below.

Deciding Between SOAP and REST

Before you spend hours fretting over the choice between SOAP and REST, consider that some web services support one and some the other. Unless you plan to create your own web service, the decision of which protocol to use may already be made for you. Extremely few web services, such as Amazon, support both. The focus of your decision often centers on which web service best meets your needs, rather than which protocol to use.

SOAP vs. REST

SOAP is definitely the heavyweight choice for web service access. It provides the following advantages when compared to REST:

• Language, platform, and transport independent (REST requires use of HTTP)
• Works well in distributed enterprise environments (REST assumes direct point-to-point communication)
• Standardized
• Provides significant pre-build extensibility in the form of the WS* standards
• Built-in error handling
• Automation when used with certain language products

REST is easier to use for the most part and is more flexible. It has the following advantages when compared to SOAP:

• No expensive tools required to interact with the Web service
• Smaller learning curve
• Efficient (SOAP uses XML for all messages, REST can use smaller message formats)
• Fast (no extensive processing required)
• Closer to other Web technologies in design philosophy

Locating Free Web Services

The best way to discover whether SOAP or REST works best for you is to try a number of free web services. Rolling your own web service can be a painful process, so it’s much better to make use of someone else’s hard work. In addition, as you work with these free web services you may discover that they fulfill a need in your organization, and you can save your organization both time and money by using them. Here are some to check out:

• Free-Web-Services.com
• WebserviceX.NET
• SwaggerHub
• XMethods

One common concern about using a free web service is the perception that it could somehow damage your system or network. Web services typically send you text, not scripts, code, or binary data, so the risks are actually quite small.

Of course, there’s also the concern that web services will disappear overnight. In most cases, these web services are exceptionally stable and it’s unlikely that any of them will disappear anytime soon. I’ve been using some of them now for five years without any problem. However, stick with web services from organizations with a large Internet presence. Research the Web service before you begin using it.

Working With the Geocoder Web Service

To make it easier to understand how SOAP and REST compare, I decided to provide examples of both using the same free Web service, geocoder.us (thank you to Mark Yuabov for suggesting it). This simple Web service accepts an address as input and spits out a longitude and latitude as output. You could probably mix it with the Google Maps API example I present in “Using the Google Maps API to Add Cool Stuff to Your Applications.”

The Bottom Line: When to Use SOAP or REST

Some people try to say that one process is better than the other, but this statement is incorrect. Each protocol has definite advantages and equally problematic disadvantages. You need to select between SOAP and REST based on the programming language you use, the environment in which you use it, and the requirements of the application. Sometimes SOAP is a better choice and other times REST is a better choice. In order to avoid problems later, you really do need to chart the advantages and disadvantages of a particular solution in your specific situation.

There’s one absolute you should get from this article. Don’t reinvent the wheel. It’s amazing to see companies spend big bucks to create Web services that already exist (and do a better job than the Web service the company creates). Look for free alternatives whenever possible. In many cases, the choice of Web service also determines your choice of protocol.

Actually, there are two. Whether you pick between SOAP or REST for your web service, making sure you thoroughly test your APIs. Ready! API has a full suite of functional, performance, security and virtualization tools for your API testing needs. You can also learn how to test RESTful APIs, in our API Testing Resource Center.