What is a SOAP API?
The SOAP API is in some ways the predecessor to the REST API, but it is distinct from REST. SOAP is a protocol, while REST is a style.
SOAP API requests and responses are formatted with XML, and while extensible, are strictly formatted and more bandwidth intensive than JSON (Java Script Object Notation). Like REST, they are transmitted with HTTP messaging, but can also use SMTP, TCP, and UDP, which can be a big benefit in the right use cases.
While XML allows for data to be described any way you like, the SOAP schema requires a specific structure around that data.
- Envelope: This part identifies the message as a SOAP message.
- Header: Information about the message. Think of the header as metadata for the message, like authentication details. If it were a real-world letter, it may contain the recipient, sender, and postage details. The header is optional.
- Body: The content of the message. This area is used for both the request and the response, depending on the direction of the message.
- Fault: This part stores information about any errors that occur in the request or response. The fault is contained within the body when an error occurs. It is also optional.
SOAP web services are still widely used, especially in enterprise and banking applications, where the strict contracts of XML schema maintain stability and structure in responses and requests. It requires more bandwidth to transmit verbose XML states with every request, but is a worthwhile tradeoff for security and functionality, including support for ws-security. It has, however, been mostly eclipsed by REST.
What is a REST API?
REST API is an architectural style which defines a set of architectural constraints for stateless communication between Application Programming Interfaces, or APIs. It is not a standard, so it allows developers some flexibility, but it acts as a mediator between users, clients, and resources. REST has become ubiquitous in API programming because it emphasizes scalability and greater interoperability, while its predecessor was a highly-structured protocol that required XML.
REST offers a number of constraints that make life easier for developers while still providing functionality and security.
- Uniform interface. If you've ever had to order a special dongle for that one piece of hardware without a USB connector, you understand the problem that RESTful APIs solve. Imagine that same problem, but on internet scale: thousands of websites talk constantly to each other, but without a translator in between. RESTful APIs act as connectors between all these clients and servers, with a standardized contract between them.
- Client-server architecture. In a REST API, a request is issued by a client to a server. A client makes a request to an API at an endpoint which it has access to. The API validates the request and passes the request to the destination server or program. The server sends a response back, first through the API, which then transfers it back to the client. This decoupling and authentication provides security.
- Statelessness. Servers don't have to store state information, and at high volume, this is a key feature of API design.
- Cacheability. A cache is a place in a network where frequently accessed data can be stored to improve load times. Optimizing the network using caching improves the overall quality-of-service by reducing bandwidth, reducing latency, reducing load on servers, and hiding network failures.
- Layered system. Developers can add load balancers or proxies between clients and servers, and it doesn't require changes on either side. Security layers can also be added.
- Code on demand. Servers can execute code on the client side to improve functionality.
What's the Difference?
REST in many ways iterated on SOAP to solve its inherent problems, and created a boom in web development as a result. They share similarities in the problems they solve, but they solve them differently.
- SOAP is a protocol, and REST is an architectural style. A protocol defines how elements in a system may interact (TCP-IP, for example) while an architectural style defines the elements and connectors in a system. REST says, if you call a REST API, you must do so in a way that it understands, and you must be able to accept its responses. You can see the APIs URLs, verbs, HTTP responses, and contract statuses- all the rules of interacting with this API are defined in the contract.
- SOAP only supports XML, while REST supports XML, HTML, and most importantly, JSON message formats. JSON is significantly more lightweight than XML, and in the mobile age, this efficiency is crucial.
- REST is used for data exchange, while SOAP exposes components of application logic as services rather than data. This doesn't mean REST can't do what SOAP APIs do, it just does them differently.
- REST is cacheable.
Which one is better?
REST now represents more than 70% of public APIs. If you don't have a compelling reason to use SOAP, use REST, because it's currently the biggest style in town. This means your API is most likely to play nicely with any API you might want to call, and be easy to use for other APIs calling yours. What compelling reasons might exist to use SOAP? There are still SOAP uses in finance and enterprise, where higher transactional reliability is required. SOAP also offers some more security features than REST, which may be required in certain use cases.
Conclusion
RESTful APIs solved a lot of problems with SOAP, and contributed to the explosion in web and cloud-native development. REST offers uniform interfaces, security by authentication, caching, and statelessness to developers. However, SOAP is not without its uses, offering more security tools and application logic control. Wondering about what happens after REST? Check out Graph-QL and gRPC for more information on the future of APIs beyond RESTful web services, and even beyond programming languages!
