REST versus SOAP. It’s been an issue for a while now. And really, they’re just two answers to the same question: how to access web services.
But deciding one over the other can be surprisingly difficult.
SOAP (Simple Object Access Protocol) is a standards-based web services access protocol that has been around for a long time. Originally developed by Microsoft, SOAP isn’t as simple as the acronym would suggest.
REST (Representational State Transfer) is another standard, made in response to SOAP’s shortcomings. It seeks to fix the problems with SOAP and provide a simpler method of accessing web services.
What about GraphQL?
Of course, GraphQL has recently made a huge splash, which we’ve spoken of at length in other articles. But it’s still not as standardized as REST and SOAP, so in this article we’re just going to focus on those two.
Both SOAP and REST have issues to consider when deciding which protocol to use.
While 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 we can’t achieve any level of standardization without them. 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.
Difficulty Depends on Programming Language
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. They 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.
Built-In Error Handling
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 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
Instead of using XML to make a request, REST (usually) relies on a simple URL. In some situations you must provide additional information, but most web services using REST rely exclusively on using the URL approach. REST can use four different HTTP 1.1 verbs (GET, POST, PUT, and DELETE) to perform tasks.
Deciding Between SOAP and REST
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 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)
• 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 over SOAP:
• No expensive tools require 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:
One common concern about using a free web service is the perception that it could somehow damage your system or network. But since they typically send you text; not scripts, code, or binary data, the risks are small.
Of course, there’s also the concern that the web services will disappear overnight. In most cases, they’re exceptionally stable and it’s unlikely that any of them will disappear anytime soon. When in doubt, stick with web services from organizations with a large Internet presence. And do some quick research on the service before you begin using it.
A Simple REST Example
Sometimes, simple is best. In this case, REST is about as simple as it gets because all you need is an URL. Open your browser – it doesn’t matter which one – and type http://rpc.geocoder.us/service/csv?address=1600+Pennsylvania+Ave,+Washington+DC in the address field. Press Enter.
You’ll see the output in your browser in CSV format:
You see the latitude, followed by the longitude, followed by the address you provided. This simple test works for most addresses in most major cities (it doesn’t work too well for rural addresses – yet). The idea is that you obtain the latitude and longitude needed for use with other web services. By combining web services together with a little glue code, you can create really interesting applications that do amazing things in a short time with little effort. Everyone else is doing the heavy lifting. You can also test your REST API with simple to use tools like SoapUI.
A Simple SOAP Example
SOAP, by its very nature, requires a little more setup, but it's still impressively simple to use.
Begin this example by creating Windows Forms application using Visual Studio. The sample code uses C#, but the same technique works fine with other .NET languages (you’ll need to modify the code to fit). Add labels, textboxes, and buttons as shown here (the Latitude and Longitude fields are read-only).
Here’s where the automation comes into play. Right click References in Solution Explorer and choose Add Service Reference from the context menu. You’ll see the Add Service Reference dialog box. Type the following address into the address field: http://rpc.geocoder.us/dist/eg/clients/GeoCoder.wsdl and click Go. Type GeocoderService in the namespace field. Your dialog box should look like the one shown here.
Click OK. Visual Studio adds the code needed to work with Geocoder in the background.
At this point, you’re ready to use the Web service. All you need to do is to add some code to the Get Position button as shown here.
private void btnGetPosition_Click(object sender, EventArgs e)
// Create the client.
GeocoderService.GeoCode_PortTypeClient Client =
// Make the call.
GeocoderService.GeocoderResult Result =
// Check for an error result.
if (Result != null)
// Display the results on screen.
txtLatitude.Text = Result.lat.ToString();
txtLongitude.Text = Result.@long.ToString();
// Display an error result.
txtLatitude.Text = "Error";
txtLongitude.Text = "Error";
The code begins by creating a client. This is a common step for any web service you use with Visual Studio (or other environments that support SOAP natively).
After you create the client, you use it to call one of the methods supported by the web service. In this case, you call geocode() and pass the address you want to work with. The result of the call is stored in a GeocoderResult variable named Result. A single address could possibly end up providing multiple positions if you aren’t specific enough, so this information is passed back as an array.
Let’s assume that no errors occur (resulting in a null return value). The example assumes that you provided great information, so it places the information found in the first Result entry into the Latitude and Longitude output. So, this example isn’t really that complicated compared with REST, but as you can see, even a simple example is more work.
The Bottom Line(s)
There are a few bottom lines here.
First Bottom Line
One is that, to the question of REST vs SOAP, the ultimate answer is: “Depends.” Each protocol has definite advantages and disadvantages. Selecting SOAP vs REST comes down to the programming language you use, the environment you use it, and the requirements. (And, as mentioned earlier, this article doesn’t even bring GraphQL into the equation yet.)
If you really want to avoid problems upfront, chart the pros and cons in your situation and play it by the numbers.
Second Bottom Line
Remember that you don’t have to reinvent the wheel. It’s amazing to see companies spend big bucks to create web services that already exist (and do a better job). Look for free alternatives whenever possible. In many cases, the choice of web service also determines your choice of protocol.
Third Bottom Line
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.
Photo source: Glyphobet.net