REST vs SOAP evolvability

Question

I get the benefits of changing link uris, but that's really not what this question is about.

What I mean by evolvability is adding new features to a service or modifying (when possible) existing ones and that's actually it.

SOAP isn't that bad as REST community tends to talk about it when it comes to evolvability. For example:

1. In REST we can add new rel - in SOAP we can add new method. Both types of old clients will continue working with new services.
2. In REST we can add new form field and set its default value - in SOAP we could have service arguments as some ServiceArgs class and add a new field to ServiceArgs. That's ugly, but it works.

What are the evolvability examples when SOAP clients break and you can do nothing about it, while REST clients are handling the situation gracefully?

Thanks!

Answer 1

SOAP is a contract-based technology. The entire client/server interaction is written up and codified in a big document (the WSDL) and must be agreed upon and honored by both sides in order for things to work. If either side decides to add features, the other side must "evolve" in lock-step with it. Both sides are completely coupled, joined at the hip, glued together, married, for ever.

The typical approach to enhancing your SOAP services is to create new WSDL documents for the new versions of the service, while also maintaining the older ones. Another technique is to create a new interface to contain new methods and inherit from the old one. The approach you describe in #1 is IMO breaking the SOAP rules, because the client and server will now be using different contracts and it only works because additive changes (like new methods) can be shoe-horned in and most of the time things will work. The moment someone makes a destructive change then the client's contract will not match the server's and it's game over. It's a difficult process to manage, which is why most organizations opt to create entirely new WSDL for each new version of the API.

REST doesn't magically make all of these problems go away, but it makes things easier to manage by not forcing you to bundle your entire distributed system's "contract" into one artifact. You're using HTTP? Great, then you get to use all of the wonderful HTTP features that the web uses too: proxy servers, URLs, content negotiation, authentication, etc. You want to communicate using JSON encoding as well as XML? Knock yourself out. It's trivial to do in REST at any time, without affecting existing clients. You want security? Fine, start challenging for authenticated credentials using HTTP's in-built support for exactly that. All of these things (HTTP, JSON, etc) are standardized and described in different places and that's exactly how it should be.

SOAP combines the transmission protocol, location information, payload description, encoding choice and RPC methods into one ginormous document. If you want to make any change to anything in that list, you need a new document. Worse still, some of those things can't be changed at all.

REST separates those things out so that the pieces can evolve independently. Your URLs (or "URIs", to be more precise) are returned at runtime and assuming the client doesn't start to hardcode them are evolvable without any changes needed to the client. Additive changes to your media types are trivial if your documentation makes it clear that new fields may appear in the future. You've also got the option of versioning your media types, allowing the co-existence of v1/v2/v3... media types within your system, and the client can pick (using the Accept and Content-Type headers in HTTP) which one they want to use.

Ever heard the joke about the Porsche owner who buys a brand new car whenever the ashtray gets full? That's SOAP. What should be a trivial change requires a major overhaul. REST gives you the vacuum cleaner. You don't have to use it, but it sure is cheaper.