Like almost all Web developers out there, I’ve always been familiar with SOAP but unlike many others (before joining Gofore), I hadn’t actually used anything SOAP related ever. When I started to develop and consume Web Services and/or APIs back in the days, I jumped straight to the REST train. Back then, SOAP seemed like old school and even worse, was based on XML. XML has many great qualities, but when a JavaEE developer deals with APIs, it doesn’t sound fun with all that overhead and complex parsing libraries.
If some of you are not familiar with SOAP and REST, I’ll explain a few fundamental differences between them. First of all, REST is not a protocol. It’s a paradigm for a set of architectural constraints. REST is all about resources with unique identifiers (e.g., unique URLs in the Web world). These resources can be consumed and manipulated through the four HTTP methods (GET, POST, PUT, DELETE). When accessed, a resource can be represented in any format such as JSON or XML. REST doesn’t care that much about anything else than the actual resources. No security, no transactions, no predefined format, no contract. Just resources. Everything else is left for the developer to deal with by other means.
SOAP, on the other hand, is a protocol. A Protocol that focuses on structured information exchange. Each message delivered over SOAP is wrapped inside an XML Envelope containing information about the nature of the message and details how to process it. SOAP is not in anyway restricting the type of the information or the methods you can use to manipulate these resources, but it always comes with detailed instructions on how to proceed with what you get. Through extensions SOAP is also a whole lot of more than a REST-like resource layer. You can get almost anything you could ever need to implement your service such as the previously mentioned security and transactions. SOAP tries to solve the whole puzzle.
In a nutshell, with REST you get easy to understand and easy to access APIs (at least for Web developers), but there is no guarantees on the structure of the message, very loose coupling between the services and lots of freedom. With SOAP, you get detailed information about the structure of the message and instructions how to process it, but because it’s not just HTTP, you need complex libraries and tools to do the processing and Web Service access for you (there are mature libraries for this such as Apache CXF). Even testing SOAP resources is hard because of the added abstraction (for consuming REST resources you only need an HTTP client). However, the complexity of SOAP also gives it more power on the protocol level and makes it possible to extend it with additional features. The tight coupling and advanced features of SOAP are useful if not mandatory in some use cases but in many cases it’s also a downside. For example, if your Web Application/Service needs both internal (e.g., for AJAX) and external APIs, you can easily combine these two if you use REST but it’s next to impossible to do with SOAP in a simple and concise way.
You can probably tell that I prefer REST to SOAP. However, the project I currently work in sounded like the dreamland for SOAP if there is one. It’s a high profile public administration’s project that is based on Service Oriented Architecture (SOA). Furthermore, the public facing services are actively used only a couple of times a year and a short period of time (when new applicants are applying to different schools during spring and autumn) which means that everything must work seamlessly under heavy load. Even a short downtime or malfunction means not only bad publicity but also a possible failure for the whole national joint application period.
Given the circumstances and the fact that the project organization is huge with different teams from several companies developing APIs independently, the APIs need to be well documented, work as expected, remain stable, and remain somewhat immutable or when altered it should be somehow communicated to the consumer services. REST might sound a bit too flexible, a bit too simple, a bit too uncoordinated, and a bit too light for the scenario. SOAP does not. It’s strict. It’s complex. It’s heavy. In another words, it’s a contract and it means business. Government level business.
The project has been ongoing for a long time, and the debate between the usage of SOAP vs REST in the project has lasted almost from the day one (to my knowledge). The current status is that in many of the services there is both but for different APIs. So far the SOAP services have worked quite nicely but have required a lot more work than the REST APIs. In addition, we have now reached a point where we have operations requiring several thousand (if not tens of thousands) requests to the other services and without multithreading in our Apache Camel routes, these operations would take days to complete. The consumed REST resources have worked without bigger problems with multithreading but the CXF library used with the SOAP resources isn’t apparently thread safe. For us, it’s going to be much faster operation to replace all the SOAP APIs with REST APIs than find a new library for working with our existing SOAP services. If SOAP had been used for other things besides just messaging (which could have been the case if there would have been only server-to-server communication) this would have been a major drawback. SOAP itself is of course not to blame but the library. Still my point was that if you try to find that one monolithic solution for all the problems and it fails, you are in big trouble.
All in all, although I’m a fan of type safety and all that kind of things, I still personally think that in most cases there’s more cons than pros with SOAP and it’s more suited to waterfall model based development than agiledevelopment. SOAP does shine on some cases, but unfortunately these cases are almost always the ones not visible to the public. REST is not perfect either and leaves much more responsibility for the developer, but still it suites better for the modern Web.