Review of “Web Services – Contract – Design and Versioning” Book

The renowned SOA author Thomas Erl has just released a new book Web Services – Contract – Design and Versioning. It is quite a lengthy book totaling more than 700 pages! It would be nice to have a more digestible primer for those who can’t afford the time to read that many pages. I haven’t read the whole book yet, but I have been reading some quite interesting chapters at my local Border’s bookstore.

Sidebar: Though a small branch, it surprisingly has two copies of the book and yet nothing else by Erl. Go figure! I’d bet that I’m the only one who has touched the book so far (the bookstore is in a non-geek part of town).

Reading books like this sort of bum me out a bit. They sound so common-sensical and self-evident that one wonders why doesn’t everyone just follow these precepts. The style of writing is cogent and idealistic. There is truly little one can disagree with. We’re all against nuclear war, right?

One problem with the book is a lack of pragmatics – rarely does one encounter such ideal circumstances in the the real world. The SOA/WS trenches “out there” are very messy and it would have been nice to address the discrepancy between what ought to be and what is. Rarely are managers well-versed in such SOA good practices to be able to understand the need (cost) to spend some up-front time thinking about schema reuse (e.g. decouple XSD from WSDL) and the various approaches and implications of contract versioning and service evolution.

Come to think of it, Erl’s next book should be devoted to the topic of effectively applying SOA/WS best practices in a less-than-ideal world where non-technical office politics most often rule! Something along the lines of Yourdon’s Death March – how about the “Implementing SOA ideals in a Death March-like project”.

I did like the discussion of the trade-offs between an XSD separate from WSDL and a combined WSDL/XSD. There is a brief mention that although desirable, this and other “best practices” are often constrained by subpar tool implememtations. I wish this topic would have been explored further – in fact a whole chapter should have been devoted to the problem how tools (i.e. stubs) limit service providers’ and clients’ abilities to truly take full advantage of WS*. Dealing with raw WSDL is a difficult chore, and tools that automate much of the mundane chores of WSDL/code mapping also introduce non-trivial complexities. Not much new here, but in my experience tools have often given “lazy” (either time-constrained or non-curious) developers a false sense of security when dealing with SOAP. Again, a dash of pragmatics would have been helpful.

The book is definitely geared toward “big-enterprise” SOA/WS, in fact “huge-enterprise” where there are well-thought out plans and strategies regarding contracts and services. It would have been good to touch upon smaller-scale WS roll-outs – be they public or internal departmental. In my experience there is a significant difference between external-facing web services on the public internet and intranet-based services. This difference can lead to quite different strategies and tactics in design and deployment.

For a public service, you would definitely want to opt for contract-first design (WSDL to stubs) for inter-op reasons and have more of an awareness of contract versioning since you have little control over your clients. For an internal service, you can get away with a code-first approach since it is so much faster to develop, and you most probably have less inter-op concerns since you control both the server and client . New incompatible versions can be rolled out with much less pain. These days in the Java world JAX-WS annotations reduce (but do not eliminate) the impedance mismatch between code-first and contract-first strategies.

One complaint is that a chapter’s authors are not identified! With so many eminent authors, it is a pity that the interested reader cannot follow up. For example, in chapter 22.1 (p. 659) there is a pretty theoretical section on compatibility which I just happened to recognize from David Orchard’s (an author) 2006 article A Theory of Compatible Versions. It would have been helpful to those who enjoy this stuff to be able to delve into the topic more. Furthermore there are no footnotes nor references! For a “serious” book this size, this is rather shocking.

Another issue I had with the book was its lack of discussion of REST and REST-ian approaches to contract versioning. Considering how widespread REST services are today, this is rather puzzling. I would have enjoyed hearing a serious “non-religious” discussion as to when a SOAP or REST approach is more appropriate. For example, REST better suits public consumer-oriented APIs (flickr, AWS) whereas WS* might be more appropriate for a complex B2B integration scenario with functionality that cannot be easily shoe-horned into a resource model with only four HTTP verbs.

There seemed to be an implicit equating of SOA with WS-* and no shedding of light on more general problems of contract versioning. REST services whose data payloads are defined by an XSD face the same problems that SOAP XSD data formats. And what about popular data formats that do not use XSD such as Atom? The Atom and AtomPub approach, with built-in extensibility, is certainly something that should be on the radar screen of service designers. Google is using Atom as the basis for many of their web APIs Рsee Google Data. However, the service operation layer РWSDL and resource model Рface quite different versioning problems. I would have loved to hear what some of the ̩minence grise authors had to say about that!

For more information, see two good preview excerpts by the authors:

There is also an excellent article that talks about real-life trade-offs and issues in contract versioning:

Tags: , , ,

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: