SOAP vs. REST: What API Testers and Developers Need to Know

SOAP or REST — it’s a question that comes up quite a bit in the world of APIs. The point of this comparison is education rather than confrontation: how to make the most of the different roles SOAP (Simple Object Access Protocol) and REST (REpresentational State Transfer) play. 

Instead of a competition as to which is better, this article is an instruction on how to make the best of both. As John Mueller accurately summarized in an earlier blog post, both are "... answers to the same question: how to access Web services." Both have their uses.

Strictly speaking, SOAP and REST aren't directly comparable: REST is an architectural style, and SOAP is a specific protocol defined by a standard. A REST-styled project might, in principle, rely on SOAP. However, architects often abbreviate a typical choice in these terms: SOAP involves relatively tight-coupling between client and server, use of standard SOAP libraries, XML payloads, and attention to the SOAP standard, while REST focuses on HTTP transport, lightweight payloads, and Fielding's model of stateless resource representation.

SOAP-based APIs and SOAP Web services tend to run more expensive than other contemporary options. SOAP relies on building XML-based systems, which means the amount of data is inherently larger, which in turn means it’ll cost you a lot more for central processing unit (CPU) and memory usage, usually to the point that you have to build custom servers to handle the load.

In broad terms, SOAP is:

  • older
  • "heavier"
  • likelier to expose business logic as opposed to data
  • more rigorously secure, transactional, and reliable
  • resistant to caching, and therefore scaling
  • restricted to XML payloads

Commonplace folklore says that REST has "replaced" SOAP. The evidence of publicly-documented APIs (Application Programming Interfaces) provided through the Programmable Web Directory makes it apparent that only a minority of recent APIs choose SOAP exclusively. Developers have gradually shifted from SOAP to REST over the last decade, as measured by catalogued APIs, searches, and surveys. In this sense, REST has taken over.

At the same time, SOAP remains effectively indispensable for APIs that need its functionality. It's no surprise that the overwhelming majority of organizations that expose straightforward data tables select REST. Create-Read-Update-Delete operations are ideal for REST. Enterprise-style APIs, though, and especially those with specific requirements for transaction and/or security protection, are easier to implement with SOAP.

Examples

MarkLogic, for instance, is a proprietary database product (and the company behind it) focused on management of massive document collections. Its REST API focuses largely on queries and other read operations. The API is thin; it provides nearly-transparent access to the underlying documentbase at the same granularity as the documentbase itself.

SOAP examples are a bit harder to exhibit: many of the best-engineered ones are used purely internally, and aren't visible outside the organizations which rely on them. Financial companies are centers of SOAP reliance. PayPal, for instance, exposed a SOAP API to its services soon after its 2002 acquisition by eBay. Authentication is crucial to this API; moreover, much of the API realizes business transactions as two-phase commits, rather than just data look-ups or simple-minded updates. One of SOAP's values is a guarantee that transactions are atomic: either the entire transaction completes successfully, or, if an error occurs, it is rolled back or restored entirely, so that the system's state is always consistent. While REST can construct such advanced functionality as transactions and reliability, these are part of the definition of SOAP; architects who choose SOAP do not have to decide on transaction contracts to support the specific applications they design.

Hard Choices

Mobile customers introduce questions about SOAP and REST that remain incompletely understood. SOAP certainly involves considerably more overhead in transmission of a single datum, and performed poorly on older equipment. It's less clear that the libraries actually used for commercial applications preserve REST's apparent advantage. Worse, though, is that SOAP was largely defined for a service-oriented architecture (SOA) between computational peers, and simply doesn't fit mobile's capability and security realities well. Mobile contexts often nullify SOAP's strengths in comparison to REST.

Transactions, reliability, and security are only three of SOAP's leading features. REST-based projects often find themselves creating definitions for error-handling, language-specific software development kits (SDKs), proxy responses, service introspection, and so on, all of which already are present in SOAP. REST undeniably makes for a quicker start; equally undeniably, many REST-based projects bog down as they try to specify functionality that SOAP builds in. 

The most challenging and frustrating aspect of choosing between them is that architects often don't have enough information about which will be better for a particular project until well after deciding between them. In the absence of complete information, we use heuristics.

Two consistent themes in comparison of SOAP and REST for specific projects turn up:

  • Are the technologies culturally compatible with the organization managing the projects? An API job is probably not the place to teach a corporate Java platoon to lighten up its approach and make the most of REST.
  • Is the business case for the project closer to, "open Web-scale access to our database", or "provide (complex) services? REST is generally a better fit for the former, SOAP for the latter.

Everything else can be negotiated, bridged, or migrated; these two dimensions--organizational culture, and data orientation — are the best predictors of technology fit in implementing APIs.

Further Resources