API 101: SOAP vs. REST

There’s a lot of talk within the application programming interface (API) industry about SOAP vs. REST that makes for a lively debate. Back in 2000, when the World Wide Web (WWW) was maturing and spreading across almost every sector, both approaches to developing APIs were also emerging. But while SOAP APIs quickly gained momentum with developers, REST APIs would begin to outpace them a decade later with the introduction of mobile applications. In our experience, they each still have their place.

So, which is right for you? It’s helpful to understand the good and the bad of both so that you can make the proper design when planning your next API (or the next iteration of a legacy API). Let’s take a closer look at these two major players in API development.

An overview of SOAP APIs

What is a SOAP API? The Simple Object Access Protocol (SOAP) was introduced in the late 1990s to help define messages exchanged between systems and used by applications. SOAP quickly became the API pattern of choice as enterprise organizations looked to build out the infrastructure they needed to do business in the new dot-com age. Unlike REST, SOAP is an actual protocol, providing you with stricter detail about what an API does, which has its own mix of benefits and potential baggage when it comes to putting SOAP APIs to work.

SOAP provides an industrial-grade API solution that is suitable within most enterprise environments. While SOAP may not be the choice of newer mobile developers or single-page application developers, it provides a solid foundation for integrating enterprise resources into other systems—and it works well with existing enterprise solutions. At the end of the day, SOAP provides a solid, reliable pattern you can use when you don’t require a more date-centric, lightweight API design pattern like REST.

The Good

• Well-Defined Protocol: SOAP is a well-defined protocol designed to handle industrial-grade APIs at scale.
• Extensible Markup Language (XML): The XML format provides a wealth of parser, generators, and validation tooling that improve the quality of API messages.
• Tooling: There is a wealth of tooling available for SOAP service, helping developers integrate and work with SOAP APIs more easily.
• Adoption: Many enterprise systems have adopted SOAP as a Data Interchange Format, which means easy integration.
• Transport: SOAP is flexible because it can use HTTP, TCP, UDP, and SMTP as a transport.

The Bad

• Verbose: SOAP uses XML, which requires more bandwidth to transmit over networks and is less desirable for mobile developers.
• Collaboration: SOAP can be a lot for junior developers to learn, and for testers and other roles to work with.
• Enterprise: It is viewed as a bulk enterprise solution, and not something you use as part of modern application development.
• Non-Developers: SOAP’s complexity may intimidate non-developers, who are often unable to put to work.
• Open Standards: There are fewer open source industry standards within SOAP universe, with a more proprietary stance on interoperability.

An overview of REST APIs

What is a REST API? REpresentational State Transfer (REST) is a software architectural style that emerged around 1999 alongside SOAP but really didn’t get as much industry adoption until the iPhone was released in 2008. Unlike SOAP, the REST style of delivering APIs is married to the HTTP specification the web is built upon. REST APIs fully utilize the uniform resource locator (URL) to make data available using the web, maximizing usage of HTTP methods, headers, the body, and the other essential web building blocks. But in addition, REST can be easily adopted within mobile applications.

Because it provides a very lightweight, simple, and widely recognized set of design patterns, REST is a common starting place for most teams when they begin investing in APIs. Organizing digital assets into domains of different REST API resources helps make sense of the digital landscape that has emerged across the enterprise in the last 25 years. Think of REST as your base design pattern, but you should also be learning other design patterns that can build off of it.

The Good

• Simplicity: REST APIs provide a simpler way to describe requests and responses, using familiar web concepts that developers understand.
• JavaScript Object Notation (JSON): As a data format, JSON is lighter and smaller as it moves over the wire, making it suitable for unreliable mobile networks.
• Languages: REST enjoys much wider language support across different programming languages, increasing its reach as an API pattern.
• Resources: It is much easier to organize and manage data, content, and media when you have them defined as simple RESTful resources.
• Adoption: REST enjoys wider adoption because it is closely aligned with HTTP and is easier to pick up and use.

The Bad

• Interpretations: There are many interpretations about what is REST and what isn’t REST, making for a loose mix of APIs out in the wild.
• Standards: REST is not a standard and doesn’t have a specific protocol for developers to follow when it comes to developing APIs.
• Resources: There is more occurring across enterprise solutions than just resources, and REST misses events, messages, and other elements.
• Protocol: REST has hitched its wagon to the request and response reality of HTTP 1.1, and may or may not apply in an HTTP/2 or HTTP/3 world.
• Myths: The world of REST is full of inaccurate myths and also dogmatic views of technology, making for a lot of uncertainties and friction when it comes to implementations.

SOAP APIs vs. REST APIs: a comparison

Whether you use SOAP or REST shouldn’t be a blanket decision, it should be project-based. Because of this, you won’t answer the SOAP vs. REST question once and be done with it. You’ll be facing this comparison in perpetuity as you evolve and expand your API strategy across your organization (which may acquire and merge with new companies), or as you change jobs throughout your career.

Some common considerations to ask yourself before choosing: Who will be consuming your API? What integrations and applications will it service? What is the history of your organization and what developers are available on your teams?

Today there remain plenty of SOAP APIs in operation across the enterprise landscape. Don’t assume that these SOAP APIs should just be directly replaced with REST APIs when working with existing enterprise software. SOAP isn’t old and outdated as many will have you believe, and REST doesn’t always represent the best path forward into the future. In the same vein, don’t dismiss REST when managing digital resources simply because it is looser and less defined than SOAP.

SOAP and REST are two distinct design patterns that you should have in your API developer toolbox, so making sure you’re informed on both is important. We’ve been having this debate for more than a decade now, and we’ll continue having it well into the next.