Why SOAP can't use HTTP caching mechanisms
I am making a transition from SOAP to REST, and I would like to convince my colleagues that this is a good move. We don't need the extra security mechanisms that SOAP can provide. For us the overhead of SOAP and WSDL has only proven to be a headache over the years.
Apart from the obvious simplifications, one really valuable advantage for our system would be the HTTP caching mechanisms. I have read things on the subject, but I still don't fully understand why these caching mechanisms can't be applied to SOAP messages.
Is it simply because REST by convention encodes all the parameters in the url? Since a GET call can also have a body with parameters, I understand that it's not restricted for REST, but the caching mechanisms don't work if you do so?
Answer
SOAP, when using HTTP as the transfer mechanism, is sent via HTTP POST requests. As HTTP POST is non-idempotent, it is not cached at the HTTP level.
REST may be cached, provided the requests in question are idempotent ones: GET, PUT and (theoretically) DELETE. Any POST requests still won't be cached. That said, if you are planning to do a lot of work with this, you should look into how caches check whether they are still valid. In particular, the ETag header will be a good way to implement caching providing you've got a cheap way to compute what the value should be.
Is it simply because REST by convention encodes all the parameters in the url? Since a GET call can also have a body with parameters, I understand that it's not restricted for REST, but the caching mechanisms don't work if you do so?
REST does not prescribe any particular mechanism for how to encode request parameters in the URL. What is recommended is that clients never do any URL synthesis: let the server do all the URL creation (by whatever mechanism you want, such as embedding within the path or as query parameters). What you definitely shouldn't do is have a GET where the client sends a body to the server! Any cache is likely to lose that. Instead, when that request doesn't correspond to a simple fetch of some resource, you POST or PUT that complex document to the server and GET the result of the operation as a separate stage.
A POST of a complex document that returns the result of the operation as another complex document is pretty much how SOAP is encoded. If you're tempted to do that, you might as well use SOAP directly as that's got much more mature tooling in many languages. If you want to run REST that way, you're probably doing it wrong somewhere…