What is a SOAP API?
SOAP API (Simple Object Access Protocol) is in some ways the predecessor to the REST API, but it is distinct from REST. SOAP vs REST simply put would be: SOAP is a protocol, while REST is a style.
The clearest analogy is in this Postman article, which compares SOAP to a National Postal Service: "(SOAP) is older, established, and dependable— but it can be slower than competing architectural styles like REST."
SOAP API requests and responses are formatted with XML, and while extensible, areand more bandwidth intensive than REST. Like REST, they are transmitting with HTTP, but can also use SMTP, TCP, and UDP, which can be a big benefit in the right use cases.
What are the parts of a SOAP API?
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 API query / request and the API payload / 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.
Are SOAP APIs obsolete?
Not at all. While REST API's are common (e.g., all Abstract's APIs use REST), SOAP is 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.
REST APIs are extremely popular, but SOAP APIs do offer a lot of functionality out of the box that REST APIs do not. They are also a good place to start if you are just learning web development, because their stricter formatting requirements are more instructional than REST, akin to learning C++ before learning Python.