High-level overview
SOAP (Simple Object Access Protocol) and REST (Representational State Transfer) are two widely used approaches for building web services and integrations. Choosing between SOAP and REST affects performance, simplicity, security, and how Salesforce interacts with external systems. This post compares SOAP and REST side-by-side and provides guidance for Salesforce integration scenarios.
Core differences
1) Architectural style vs. protocol
SOAP is a protocol with strict standards defined by the W3C. It prescribes an XML-based messaging format, envelope structure, and rules for headers, faults, and bindings. REST is an architectural style that uses standard HTTP methods (GET, POST, PUT, DELETE) and can transfer data in multiple formats (JSON, XML, etc.). REST relies on HTTP semantics rather than a formal protocol.
2) Message format
SOAP messages are always XML and wrapped in a SOAP envelope. REST most commonly uses JSON (especially with Salesforce REST APIs) but can use XML or other formats. JSON payloads are typically smaller and easier to parse in modern web/mobile applications.
3) Transport and operations
SOAP can use several transport protocols (HTTP, SMTP, TCP) but is usually run over HTTP. REST exclusively leverages HTTP and its verbs. REST maps CRUD operations to HTTP methods, while SOAP exposes operations as RPC-like methods defined in a WSDL.
4) Service description and typing
SOAP provides a formal contract using WSDL (Web Services Description Language) and strongly-typed schemas (XSD). This enables code generation, strict validation, and tooling support — useful for enterprise integrations. REST typically uses informal documentation, though OpenAPI/Swagger adds a machine-readable contract for many REST APIs.
5) Security
SOAP has built-in standards for security (WS-Security) including message-level encryption, signatures, and tokens. REST commonly uses HTTPS/TLS for transport security and leverages OAuth 2.0, JWT, or API keys for authentication and authorization. For end-to-end message security across intermediaries, SOAP’s WS-Security offers richer options.
6) Statefulness
SOAP supports both stateful and stateless operations depending on the implementation. REST is inherently stateless: each request from client to server must contain all information needed to process the request. Statelessness simplifies scaling and caching in RESTful systems.
7) Error handling
SOAP has a standardized fault structure in the SOAP envelope. REST relies on HTTP status codes (4xx/5xx) plus response bodies for detailed error information. Proper use of status codes makes REST error handling straightforward for clients and tools.
8) Caching and performance
RESTful APIs can benefit from HTTP caching (Cache-Control, ETag) which improves performance and scalability. SOAP responses are harder to cache due to envelope complexity. REST with JSON tends to be lighter weight and faster to parse.
Examples
Simple REST request (curl)
Example: retrieve an Account in Salesforce REST API
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Accept: application/json" \
https://yourInstance.salesforce.com/services/data/v56.0/sobjects/Account/001XXXXXXXXXXXXXXX
Simple SOAP request (Envelope)
Example: a SOAP login/envelope pattern (simplified)
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com">
<soapenv:Header/>
<soapenv:Body>
<urn:login>
<urn:username>[email protected]</urn:username>
<urn:password>passwordTOKEN</urn:password>
</urn:login>
</soapenv:Body>
</soapenv:Envelope>
When to choose which (Salesforce-focused guidance)
Choose SOAP when:
– You need strict contracts, strong typing, or auto-generated client stubs from WSDLs.
– You require advanced message-level security (WS-Security) or need to work across non-HTTP transports.
– Integrating with legacy enterprise systems that provide SOAP endpoints.
Choose REST when:
– You prefer lightweight, JSON-based payloads for mobile/web clients.
– You want to leverage HTTP caching, scalability, and simplicity.
– You are building modern integrations with OAuth 2.0 and need straightforward HTTP semantics (Salesforce REST APIs are ideal).
Best practices for Salesforce integrations
– Use Salesforce REST APIs (or Bulk REST APIs) for CRUD-heavy, high-volume, modern integrations.
– Use SOAP APIs if you rely on WSDL-based tools, need metadata operations supported by the SOAP API, or require WS-Security features.
– Always secure traffic with TLS and use OAuth 2.0 for REST integrations to follow Salesforce recommended practices.
– Consider API limits and batching (Composite and Bulk APIs) when designing high-volume integrations.
Conclusion
SOAP and REST serve different needs. SOAP provides formality, standards, and advanced security features. REST provides simplicity, lighter payloads, and scalability. For most modern Salesforce integrations, REST (JSON + OAuth) is the preferred choice — but SOAP remains valuable when formal contracts, legacy compatibility, or message-level security are required.