Here’s my take.
-
Although coming from a Java standpoint, I actually prefer REST. SOAP envelope with multiple namespaces and its complex structure is abomination. It tries to solve mostly imaginary problems, and doesn’t solve anything efficiently. Only thing about SOAP I’ve found useful is that it has standards for authorization and errors. On the other hand, both could be solved much easier by including four standard attributes in root XML element – username, password, errorCode, errorDescription.
-
Good API description and documentation is indeed all that matters. Difference between REST and SOAP in mature framework is mostly in a few lines of configuration.
-
For SOAP, send hash as part of SOAP security; for REST, I like to package everything in payload and avoid HTTP headers for authentication. I have only subjective reasons though, since I had to battle with frameworks which don’t easily expose HTTP headers.
-
My personal preference is having different URIs for different protocol versions. In my experience, this gives you more flexibility in newer versions, and old clients which connect to unsupported versions of a protocol stop working immediately and for obvious reasons. Also, sometimes you can map old version of application to old URI, to avoid having legacy support code in new server version.
As for how long you support old version of protocol… ideally, as long as you have clients which use it. This is more business than technical decision. You should support at least one previous protocol version. It’s usually in your interest to push clients towards new version to lower legacy support costs; from the clients side, new version should mean new features, better protocol, and some sort of additional business incentive (if new features alone are not enough).