SOAP vs REST Integration – When to Use Each

Integrating external systems with Salesforce requires choosing between SOAP and REST APIs. This guide explains the differences and when to use each approach.

1. REST API Overview

Advantages

• Lightweight and faster
• Simpler to implement and test
• Better for mobile and modern applications
• Lower bandwidth usage
• Stateless architecture

Example REST Callout

public class RESTCalloutExample {
    public static void callExternalAPI() {
        Http http = new Http();
        HttpRequest request = new HttpRequest();
        request.setEndpoint('https://api.example.com/users');
        request.setMethod('GET');
        request.setHeader('Authorization', 'Bearer token');
        request.setTimeout(120000);
        
        HttpResponse response = http.send(request);
        if (response.getStatusCode() == 200) {
            System.debug('Response: ' + response.getBody());
        }
    }
}
  

2. SOAP API Overview

Advantages

• Strict XML-based protocol with strong contracts
• Built-in security and reliability
• Better for complex transactions
• Ideal for legacy system integrations
• WS-Security standards support

Example SOAP Callout

public class SOAPCalloutExample {
    public static void callSOAPService() {
        Http http = new Http();
        HttpRequest request = new HttpRequest();
        request.setEndpoint('https://api.example.com/soap');
        request.setMethod('POST');
        request.setHeader('Content-Type', 'text/xml;charset=UTF-8');
        request.setHeader('SOAPAction', 'http://example.com/action');
        
        String soapBody = ''
            + ''
            + ''
            + '123'
            + ''
            + '';
        
        request.setBody(soapBody);
        request.setTimeout(120000);
        
        HttpResponse response = http.send(request);
        System.debug('SOAP Response: ' + response.getBody());
    }
}
  

3. REST vs SOAP Comparison

Feature	REST	SOAP
Protocol	HTTP Methods (GET, POST, PUT, DELETE)	XML-based, typically over HTTP
Message Format	JSON (preferred), XML, Plain Text	XML (strict)
Performance	Faster, lightweight	Slower, verbose
Learning Curve	Easy	Steep
Caching	Built-in HTTP caching	Limited caching
Error Handling	HTTP Status Codes	SOAP Faults in XML

4. When to Use REST

• Building modern APIs and microservices
• Mobile and web applications
• Public APIs
• Cloud-to-cloud integrations
• Real-time data streaming
• When bandwidth is a concern

5. When to Use SOAP

• Legacy system integrations
• Enterprise services requiring strict contracts
• Complex transactions requiring guaranteed delivery
• Systems with WSDL (Web Services Description Language)
• Need for WS-Security and advanced security features
• Highly regulated industries requiring audit trails

6. Best Practices

For REST Callouts:

• Use Named Credentials for secure authentication
• Implement proper error handling and retry logic
• Parse JSON responses efficiently using JSONParser
• Set appropriate timeouts (120 seconds max)
• Monitor API rate limits

For SOAP Callouts:

• Generate stubs from WSDL using Apex Web Services
• Handle SOAP faults appropriately
• Validate XML structure before sending
• Consider using Apex-generated SOAP client classes

7. Decision Tree

Is it a modern API?
├─ YES → Use REST
└─ NO → Is it a legacy system?
        ├─ YES → Check if it has SOAP/WSDL
        │        ├─ YES → Use SOAP
        │        └─ NO → Use REST
        └─ NO → Use REST (modern approach)