When to use SOAP instead of REST

With SOAP you have a contract between the two parties.

With REST you'll have to implement such contract yourself in your code.

For me SOAP is like a strongly typed language. REST is like PHP : quick to get something going.

As for performance related to the size of the message that needs to be transported: People often assume that with SOAP huge amounts of very verbose XML needs to be transported. Technically this is true but in modern days the two endpoints will most likely use gzip compression and/or FastInfoset. This greatly reduces the size of the message, possibly to the size of compressed JSON. However some people argue that JSON is still somewhat faster to parse than is XML. This is possibly true but I believe the difference in parsing speed for most use cases is negligible. I've also seen tests where FastInfoset parsing outperforms JSON parsing. All in all arguments need to be reviewed in the light of the current state of affairs, not the way the world looked in 2005.

I recently had to implement a web service where the request could become very large (several megabytes) and the reply even bigger. This works well with SOAP. Contrary with REST the conceptual idea is that you embed the request as part of URL and such approach of course only works for very small amount of request data. REST camp will say that you have two choices: (1) You embed your large data in a the body of a POST request but this is not really a 'true' REST way of doing things or you (2) change your design so that you send many questions rather than a single big question but such solution will of course create a lot more network overhead because of the roundtrip.
I stayed with SOAP for this particular service.

REST is fine and possibly the optimal choice for most scenarios but there are certainly cases where SOAP is a better fit, IMHO.

One of the major benefits of SOAP is that you have a WSDL service description. 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). Note that with version 2.0, WSDL supports all HTTP verbs and can be used to document RESTful services as well, but there is a less verbose alternative in WADL (Web Application Description Language) for that purpose.

With RESTful services, message security is provided by the transport protocol (HTTPS), and is point-to-point only. It doesn’t have a standard messaging system and expects clients to deal with communication failures by retrying. SOAP has successful/retry logic built in and provides end-to-end reliability even through SOAP intermediaries.

One of the major benefits of RESTful API is that it is flexible for data representation, for example you could serialize your data in either XML or JSON format. RESTful APIs are cleaner or easier to understand because they add an element of using standardised URIs and gives importance to HTTP verb used (i.e. GET, POST, PUT and DELETE).

RESTful services are also lightweight, that is they don’t have a lot of extra xml markup. To invoke RESTful API all you need is a browser or HTTP stack and pretty much every device or machine connected to a network has that.