I study service description contracts as a key difference between REST and SOAP, as part of my series comparing Resource Oriented Architectures and Service Oriented Architecture. In the
previous article on ROA and SOA I examined what ROA and SOA are as objectively as I could. Now it's time to state some opinions on how the differences play out in an enterprise setting by studying the practical considerations regarding service description contracts with adopting ROA or SOA. These are non-technical considerations that an enterprise has to think about when deciding on what to adopt.
In the previous article, I found three key differences between ROA and SOA:
- Contractual vs Not - SOA offers contractually, discoverable interfaces, while and ROA expects designers to solve problems as they see fit.
- Rich vs Uniform Behavior - ROA has the uniform interface applied with minimally overloading, while SOA provides rich, discoverable behavior
- Differentiation vs Equivalence of Data and Metadata - SOA relies on metadata to inform behavior, while ROA uses connectedness and design time conventions for representations and URI's to blur data and metadata together.
Today I study the value of web service description contracts, in a typical enterprise development setting.
My conclusion: I think enterprise settings mostly need service descriptions. A contract levels the playing field between service provider and client which is important when organizational politics might get involved. Otherwise the provider has all the power and the proliferation of unstandardized web service providers in an enterprise setting will take an huge toll. Lack of a contract certainly gives service providers freedom. That's great if you are a provider as there's no one to answer to. It's terrible if you need to be the client of 20 different kinds of web services, since basic questions like "what URL do I POST to and what do I POST to get a list of X's with property Y" will be documented 20 different ways. While efforts like
WADL and
NSDL offer solutions, these have to be institutionalized into ROA for it to be viable in the enterprise, and frankly the REST people resist contracts for reasons that appear cultural. The sad thing about all this is that REST is not incompatible with contractual service descriptions, there just are no warmly embraced standards for them to correspond to WSDL in SOAP.
Recall with horror how hard it is to maintain an application if SQL has leaked throughout the layers, especially to my view code. Somebody moves an entity attribute to another table and "ack!" we've got tons of duplicated code to fix. Now consider the weak correspondence between GET, POST, PUT, DELETE and the CRUD operations. Now consider that the URI query parameters are your new form for expressing WHERE clauses, and that, unlike SQL, web services are a distributed technology so you don't control the analog of the database schema. Now consider that you can't encapsulate these URI's because they are designed to be universal addresses. Links could be in your source code, in your data, or in your end user's bookmarks and emails. REST depends a little too much on links not breaking and POST parameters not changing to NOT express this in a contract.
In order to use any web service, the caller must know the technical details about how to invoke it. WSDL helps SOAP solve this problem. The WSDL spec is admittedly a bit over-engineered, and solves a much broader, more abstract problem than what SOAP over HTTP alone requires. The bloat is a minor flaw, and is greatly overstated by detractors. I often look at raw WSDL in an editor.
But really, who cares how ugly it is or isn't? As long as the tools eat it, I'm happy. And WSDL is very well tooled because the IT industry invested heavily in SOA. Most of the kinks have been worked out by now, so that if you follow the WS-I recommendations, you get great interoperability that's easy to use. Stick the WSDL it in your favorite SOAP stack, whether that's one of a dozen in Java, or C#, Ruby, Erlang or whatever. And then forget about it. Visual WSDL explorers are appearing, like the one the Eclipse web services plugin provides.
I hear the REST people saying "how hard is it to GET and POST to the URI - why do we need a web service description?". It's not very hard as long as you know everything in this list:
- The server that hosts the service
- The URL path structure to the resource you want
- The required and allowable query parameters after "?" in the URL
- What values are allowable for each parameter
- What type of response you will get back
For an example, let's look at GData atom feeds from google. Items 1-4 are defined by the
GData API Protocol Reference and item 5 is defined by the
Atom RFC. Google and ATOM have done a great job of defining a nice RESTful architecture, and I expect it's pretty efficient and I think they got it right. We'll see below they're in the suite spot for using ROA.
But let's look at what it took to create this solution and ask if we can replicate this in the enterprise when we serve up enterprise data instead of blog feeds. Instead of an instance of a WSDL and a discoverable XML Schema contained in it, we have to find something that corresonds to the ATOM spec itself, which stands on its own 42 pages (and ATOM is a VERY simple mechanism). ATOM is nicely written and readable, but every ATOM tool maker should read and understand it because the spec is all you get.
ATOM is a widely known enough standard to have attracted tool makers to help. The problem is that that only helps when I make web services for things like ubiquitous blog feed formats backed with open standards. The tooling that chews on WSDL applies to *ALL* SOAP services. That's the difference without contracts: every service with a different payload paradigm is a one-off. I think this hints at an economic reality: ROA without service description contracts is indicated when the economics favor a very large, diverse set of web service clients that can collaborate on tooling up with format-specific solutions.
There's one special case that deserves comment: if the ROA web service supplies clients (such as a UI) within the same development team, then you can get reuse of tribal knowledge of the payload format. In such settings, you probably can be agile with what the web service provides, so long as no other parties are depending on it for critical business processes. I think of this as ROA in the MVC layer and not really as enterprise web services. This kind of ROA might often prefer JSON over XML and dazzle us with mash-ups. In summary, ROA without contracts works well within shouting range or globally, but not as well as SOAP/WSDL in between. Another way to state the same thing: if organizational politics are involved, you need contracts governing your web services.
Also, don't forget that to use a specific web service like GData, the GData API style information has to be created, maintained, communicated, and understood. These are all costs accrued per resource type. To be fair, before you call a web service to make a state change you need to understand what is going to happen in a way code reading the WSDL can't help with. But WSDL provides a natural place to describe the operations in human readable form, though admittedly like any form of code documentation, getting developers to create it will be a challenge in an enterprise setting. Still this improves over REST which offers no convention at all for a natural home for the description of what to POST to a given URL.
The key difference is this: with ROA, somebody has to create written specs like the GDATA API and the ATOM standard FOR EVERY distinct resource type. A resource provider might choose to use the same XML marshaling tools as in SOA to create XML Schemas or DTD's, or they might decide validation is to restrictive and force clients to read their stellar natural language description, like the ATOM team did. To describe what URL's GET or POST what entities, you have no help. REST is a programming language that hides the input and output types of it's call parameters and forces you to read documentation to know what they are.
In a corporate setting most of these specs corresponding to the GData API have to be created in house and would be maintained as documentation (and we all know how well internal IT shops do at maintaining documentation). Contrast this with WSDL that is going to roll out of your tools and be definitive, since it's a code level artifact.
Also consider what happens if you have 10 different RESTful services to deal with as a consumer. For each of them, you have to figure out all five of the elements above. Every service will have different semantics for invoking it and dealing with the response. That is, unless you adopt (and enforce) a standard for how to express these within your enterprise. Then the question arises, if instead of bolting on SOA features to ROA by spending your company's IT time and effort for no business value, why not just start with SOA and get the benefit of tooling created by the massive investments by Microsoft, IBM, Apache, Sun, Oracle, and so on? For this reason alone, I don't think ROA is ready for the enterprise in 2007. But let me be clear: this is a solvable problem and it only applies in settings where organizational interactions come into play.
Next time, I'll talk about the Uniform Interface vs rich behavior, and here, I think I see some wisdom in the ROA position.
Technorati Tags:
roa soa web-services REST SOAP WSDL interfaces
