Overview
SOAP and REST are two widely used web service styles for integrating systems and exposing APIs. Understanding their differences helps architects and developers choose the right approach for a given integration—especially in enterprise environments like Salesforce integrations.
When to use SOAP vs REST
SOAP (Simple Object Access Protocol) is a protocol with a formal standard, built-in error handling, and strong support for advanced enterprise features (security, transactions, reliable messaging). REST (Representational State Transfer) is an architectural style that uses standard HTTP methods and is optimized for simplicity, performance, and scalability.
Key differences
Protocol vs Architectural style: SOAP is a protocol with strict standards (WSDL, XML envelopes). REST is an architectural style that leverages HTTP and can use multiple formats (JSON, XML, text).
Message format: SOAP uses XML exclusively and wraps payloads in a SOAP envelope. REST commonly uses JSON (lightweight) but can also use XML, HTML, or other formats.
Transport: SOAP typically uses HTTP(s) but can work over SMTP, TCP, etc. REST strictly uses HTTP(s) and relies on HTTP verbs like GET, POST, PUT, DELETE.
Statefulness: SOAP supports stateful operations (via WS-* specs). REST is stateless by design—each request contains all the information needed to process it.
Standards & Extensibility: SOAP has a rich set of standards (WS-Security, WS-AtomicTransaction, WS-ReliableMessaging). REST relies on existing web standards (HTTP, URI, MIME types) and often uses OAuth for security.
Error handling: SOAP defines standard fault structures inside the SOAP envelope. REST uses HTTP status codes (4xx/5xx) and can return structured error bodies (e.g., JSON error objects).
Tooling & Discovery: SOAP uses WSDL for service contracts and strong typing, enabling auto-generated client stubs. REST has no single standard for discovery, though OpenAPI/Swagger fills that gap.
Practical considerations
Performance: REST + JSON is usually lighter and faster over the wire than SOAP + XML.
Security: Enterprise integrations requiring WS-Security features (message-level encryption, digital signatures) often use SOAP. For most web/mobile APIs, HTTPS + OAuth (REST) is sufficient and simpler to implement.
Transactions & Reliability: If you need ACID-style distributed transactions or guaranteed delivery that’s standardized, SOAP with WS-* specs is a better fit.
Examples
SOAP request (simplified):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:examples:wsdl">
<soapenv:Header/>
<soapenv:Body>
<urn:CreateAccount>
<urn:Name>Acme</urn:Name>
</urn:CreateAccount>
</soapenv:Body>
</soapenv:Envelope>
REST request (example using JSON):
POST /api/accounts HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "Acme"
}
Summary
Choose SOAP when you need strict contracts, advanced enterprise-level features, or standardized WS-* capabilities. Choose REST when you want simplicity, better performance for web/mobile clients, and easier adoption using JSON over HTTP. In many modern Salesforce integrations, REST (via the REST API) is preferred for lightweight CRUD operations, while SOAP (via the SOAP API) remains useful for legacy systems and cases that need richer WS-* support.