How do you choose between RESTful and SOAP APIs for your project?

A RESTful API (Representational State Transfer) is an architectural style for designing networked applications. It leverages the HTTP protocol and its methods (GET, POST, PUT, DELETE) to manipulate resources identified by unique URLs. RESTful APIs are characterized by their simplicity, scalability, and statelessness. They typically use lightweight data formats like JSON or XML for data exchange and are widely compatible with various platforms and programming languages. RESTful APIs are commonly used in web and mobile applications, offering flexibility and ease of use for developers.

A RESTful API is an architectural style for designing networked applications. It uses HTTP requests to perform CRUD (Create, Read, Update, Delete) operations. Example: Twitter API enables users to post tweets via HTTP requests.

Yes indeed, that is the question I'd ask. What is SOAP? SOAP is a tired, verbose, pretentious framework that is no longer relevant. The combination of simple JSON and REST beats SOAP anyday. It's quick to put together, fast to get up and running and performs much better to boot. And with gRPC, you have the option of a fast, modern IPC stack that can push your service even further than where simple REST can take you. So, what is SOAP? And more importantly, why bother?

SOAP (Simple Object Access Protocol) is a protocol for exchanging structured information in web services. It uses XML (eXtensible Markup Language) for message formatting and can utilize different transport protocols such as HTTP, SMTP, or others. SOAP APIs offer advanced functionality, including security, transactionality, and reliability. They are known for their interoperability, allowing systems developed in different technologies to communicate seamlessly. SOAP is often used in enterprise-level applications and industries that require compliance with standards such as WS-Security and WS-Policy.

Not many of us can choose the underlying technology on the server side. For SOAP APIs there are several abstraction technologies which move the end user away from needing to know the minutiae of the underlying transport layer. For REST APIs, end users often work with http-level code whether checking for http error codes or pulling error codes out of the header or body. I would claim the primary benefit of SOAP over REST is the abstraction away from base-level http manipulation. For the libraries I used often, a close second is not needing to know how to decompose the networking packets into Java objects.

RESTful APIs offer advantages such as simplicity, ease of use, scalability, and compatibility with various platforms. They provide flexibility in data formats and response types. However, RESTful APIs may lack some advanced features and standards found in SOAP APIs. SOAP APIs excel in functionality, interoperability, and compliance, making them suitable for enterprise systems and legacy integration. Yet, SOAP APIs tend to be more complex, require more bandwidth, and have a higher learning curve. The choice depends on project requirements, with RESTful APIs favored for lightweight applications and SOAP APIs for advanced enterprise solutions.

Some might say that SOAP is a standardised framework that abstracts the developer away from the underlying nuts and bolts of the transport protocol (http). For example, you don't have to check error codes and pass authentication tokens around in headers. I ask you, is that enough? Personally, I don't think so. JSON offers easy, transparent binding (via annotations) that make SOAP look like CORBA (yes, that's what I thought too - what is CORBA?). And yes, you the developer of the API need to know what you're doing. But come on - is http that hard? It's far easier than struggling with SOAP binding libraries! And its easy enough to provide a client library to consumers, if they struggle with http! So, why SOAP?

I don’t. Never make a SOAP API. The advantages that once existed have been outmatched in forms other than REST. SOAP’s advantage was that you could have multiple properties on different values, and you were able to notate and document your data using the format itself, but GraphQL and REST documentation tools like Swagger have eliminated the need for XML (SOAP’s format). You will have to call SOAP API’s, as many of Salesforce, Telecommunications, and Bank’s APIs are legacy and use yesterday’s technologies, but peer pressure isn’t a good enough excuse to pass it along.

Answer: Run screaming away from SOAP. Always use REST with JSON as the interchange format. SOAP and XML are over-engineered nonsense whose libraries are just fantastic breeding grounds for vulnerabilities. REST and JSON, by contrast, are relatively small and easy to understand, and JSON is well-supported by just about every programming language out there.

When deciding between RESTful and SOAP APIs, consider factors such as simplicity, scalability, compatibility, and flexibility. RESTful APIs are lightweight, easy to use, and suitable for web and mobile applications. They excel in scalability and work well with different programming languages. SOAP APIs offer advanced functionality, interoperability, and compliance with standards, making them ideal for enterprise-level applications and legacy systems. Assess your project's requirements, such as the need for advanced features or adherence to specific industry standards, to make an informed decision.

We developed SOAP-based web-services a lot in 2010s using .NET technology stack. Advantages and disadvantages are fairly described in the article. I would say, SOAP usually takes more implementation effort and more execution time. RESTful is more popular in our recent projects. It has better support on many technology platforms, e.g., Python, Node.js, Golang... By default, now I would use RESTful approach. There can be specific cases where SOAP is more appropriate to go with.

Unless you're dealing with legacy systems, that's not a question you would generally ask today. Yes, SOAP can still be used for new projects but it's not the direction the industry is heading. If you really need RPC-style web services there are more modern options like gRPC. GraphQL is also a common modern alternative which shifts a lot of the control from API teams to consumers which can often significantly speed up development.

Depends on the technology behind the integration. For Java, the Salesforce WSDL files behind the Enterprise and Partner APIs are easily converted into SOAP-based JAR files. The end user doesn't need to know what's going on underneath, instead they manipulate Java objects. Other technologies may have a similar abstraction layer, though they're less de-facto standard than the JAR files in Java. There are also REST endpoints in the Salesforce APIs, but in my experience nothing comes close to the simplicity of using the JARs. Even authentication is more convoluted where pure REST access requires an OAuth "Connected App" (Salesforce term) added on the Salesforce end to perform username/password authentication.

If you need something procedural just use REST controllers and forget about SOAP. And yes, use JSON instead of XML. As a tip, you may want to use GET more widely, even the semantics is not read-only, this way you provide a simple way of debugging but simply typing the URL in the browser.

In my experience, SOAPs more rigid basis results in a better understood API for people to to work with, while it may take more development and testing effort to get the API up and running its output is better consumed by software calling and using that API. With REST I am finding that it’s flexibility results in inconsistent implementations, particularly around where errors and error detail is presented. Both suffer when the word ‘standard’ is coupled to them with the software they are released in which leads to anyone expecting to be able to plug in and use a vendors ‘standard API’ inevitably find it to be nothing of the sort. As a preference, I’ll still side with REST as it’s other adv such as performance but I do so with caution.