Why prefer REST over SOAP?

Question

If I need a web service to pass back and forth a complex object, is there a reason I should prefer SOAP over REST? Here is an example of the possible SOAP message:

<soap:Envelope>
  <soap:Header>
    <Credentials>
      <User>Joe</User>
      <Password>abc123</Password>
    </Credentials>
  </soap:Header>
  <soap:Body>
    <MyComplexBusinessObject>
      <Search>
        <First>Joe</First>
        <Last>Smith</Last>
      </Search>
      ...
      ...
    </MyComplexBusinessObject>
  </soap:Body>
</soap:Envelope>

Using REST, I would be asking the client to POST the following xml and authenticate using Basic Authentication:

<MyComplexBusinessObject>
  <Search>
    <First>Joe</First>
    <Last>Smith</Last>
  </Search>
  ...
  ...
</MyComplexBusinessObject>

The SOAP message is slightly more complicated, but not by much. They are still both XML, but SOAP comes with a WSDL and most programming environments will generate proxy classes for you. However, most people I talk to say I should use REST instead because it's easier to use. But I don't see how SOAP is any harder to use.

Am I missing something?

Answer 1

Your first requirement of "passing back and forth a complex object" constrains your architecture to eliminate many of the benefits of REST. SOAP is designed for accessing remote objects, REST is not. REST supports passing media-types as simple as text/plain, which is far more primitive than dealing with an object.

If you haven't seen it already, this question and its answers cover most of the REST vs SOAP issues.

Answer 2

One major benefit of REST is that all you need to call and use it is a browser and a HTTP stack - pretty much every device and machine has that. So if ease of use and reach are you main goal - use REST.

One of the major benefits of SOAP is that you have a WSDL service description and you can pretty much discover the service automatically, and generate a useable client proxy from that service description (generate the service calls, the necessary data types for the methods and so forth).

So if discoverability and a strict, formal service description are more important to you, use SOAP (with the downside that you need a full-fledged SOAP client to call your service - your web browser won't be sufficient).

SOAP isn't harder to use - but it's just not quite as "pervasive" in terms of being available - any browser can call a REST service and get an answer - but then it needs to parse and interpret that response. SOAP gets nice data structure, but you need a SOAP client for this.