Book Review: Web Service Contract Design & Versioning for SOA

My wife will see any movie starring Sean Connery, no questions asked, no review required. I, on the other hand, will read anything Thomas Erl publishes, although I think I will at least limit that promise to the domain I've seen his work in, which is service-oriented architecture and web services. In that domain, the books he has published are unique in their ability to sharply focus on the important and relevant details that I need to know about. He has continued his outstanding work in the new book Web Service Contract Design & Versioning for SOA, published by Prentice-Hall in October of 2008.

This book is different in one way from the other Thomas Erl books I've read. Instead of just Thomas Erl in the credits, there are actually 9 different authors, with Thomas Erl being the "lead" author (I would assume). I suppose this is somewhat understandable, as this is also the largest book in this series that I've read (718 pages of non-appendix content), so I won't apologize for the length of this review. Considering the range of topics covered, I give them credit for being able to limit the scope of the book down to what they did, to let them focus strictly on issues with design of the web service contract. For instance, if the scope of the book was extended to give a good treatment of WS-Security, it would have expanded into areas that would detract from the main point of the book. As in the other purely SOA and web-service focused books in the series, this book carefully avoids talking about any implementations of these specifications (these are planned for later books), to continue the focus on the design of the contract.

The book covers contract design and versioning, divided into three main content sections, although the third section on versioning is small compared to the two sections on contract design, which are divided by "fundamental" and "advanced" contract design.

The book uses a fictional case study throughout the book to help us focus on making it "real". These case study sidebars are sometimes quite detailed, covering design decisions and options that we'll probably have to make in our own services.

The first section, "Fundamental Service Contract Design", starts with a foundation seen elsewhere in the "Principles" (SOA - Principles of Service Design) and "Concepts" (SOA - Concepts, Technology, and Design) books in the series. Most important here are the "design principles" (Abstraction, Loose Coupling, etc.) which contribute towards the specific goals and benefits of "service-oriented computing".

This section continues with a chapter that breaks down the various pieces of a WSDL and explains their purposes and relationships, from a high level (no syntax yet). This chapter also introduces the fact that both WSDL 1.1 (what virtually all of us use now) and WSDL 2.0 (anyone out there?) will be covered in parallel in the book. Each section that talks about an issue specific to one version will do the same for the other version. In most cases, this is done clearly to prevent confusion. This chapter also introduces WS-Policy and WS-I, in general.

This is followed by a concise chapter on namespaces and prefixes, and the various issues these present in this domain. It goes into detail of why a namespace is a URI, and not a URL, but also covers in detail the tradeoffs for treating it like a URL.

The next chapter gets into the syntax of XML Schema, going into depth with the details of defining types and messages. I liked that some features of XML Schema are de-emphasized, or not even mentioned, if they tend to be problematic in real implementations. I learned about how the "elementFormDefault" attribute really works (whether local elements are assumed to be in the target namespace). I was misinformed about this previously. This chapter has a long case study sidebar using the ideas presented in the chapter.

The next two chapters begin the fundamentals of WSDL design, down to the syntax level. The two chapters are divided by "Abstract" and "Concrete" portions of the contract. Besides the syntax, these chapters cover several common conventions and recommendations for naming and structure, from the WS-I specification, and just from common sense. These chapters focus on WSDL 1.1, but NOTE boxes are shown for places where WSDL 2.0 differs from 1.1.

The short chapter that follows focuses directly on WSDL 2.0 and what new features it provides over WSDL 1.1, and what new options it presents.

The next chapter begins detailed discussion of the first of two WS-I specifications focused on in this book, the WS-Policy specification. It hints at the ability of the WS-Policy framework to extend the behaviors and semantics of many aspects of the contract, and to do this in a reusable way.

The next chapter, the last chapter in the first section, opens up the SOAP envelope, covering the various parts, with mentions of variances between SOAP 1.1 and SOAP 1.2. This chapter introduces the notion of how SOAP messages are represented while bouncing around the network, between SOAP intermediaries, and how information about the "role" of various nodes in the network are described, and which roles can or will process particular parts of the envelope.

Now begins the second section, titled "Advanced Service Contract Design". This section, with eight chapters, covers advanced design aspects of XML Schema and WSDL, along with WS-Policy and WS-Addressing. Each of these four topics is covered in two chapters each. The first two chapters cover issues with flexibility and reusability, covering wildcards, "generic vs. specific" elements, include/import, key/keyref, and some other topics. It concludes with the usual case study examination of applying these ideas.

The next two chapters, on advanced WSDL design, focuses initially on issues of modularity and extension, then covers designing asynchronous operations utilizing WS-Addressing and WS-Policy, and WS-BPEL extensions to WSDL. It then covers some miscellaneous topics mostly covering message dispatch challenges. Note that one section discusses an example using both the "addressing wsdl" and "addressing metadata" specifications at the same time, which according to my human resources does not work, as they conflict with each other. The chapter continues with an interesting section on binding services to HTTP without SOAP. The case study at the end of the chapter expands on this idea.

The following two chapters fully explore WS-Policy and what you can do with it. It's a small language, but it shows how it can provide very complex functionality by building on it, perhaps to the point where it could be hard to understand. A case study example using WS-Security is quite complex. The explanation of the difference between "wsp:Ignorable" and "wsp:Optional" is clear with a simple example. The last of the two chapters focuses mostly on building custom policy assertions. This demonstrates a lot of its subtle power, and how the use of it may expand as specifications and implementations advance over time.

The last two chapters of this section fully explore WS-Addressing. The simple use case of replacing the SOAPAction HTTP header with the "wsa:Action" SOAP header is barely the start of what you can do with it. It presents so many unusual possibilities, like allowing WSDLs and messages to specify asynchronous messages and dynamic routing paths, along with additional metadata for each "endpoint reference" to get carried along to each endpoint.

The last section of the book, with four chapters, covers the range of ideas in service contract versioning. It goes through a "fundamentals" chapter that defines terms and basic issues, then a pair of chapters on WSDL and XML Schema versioning, and then an "Advanced" chapter (miscellaneous issues) to end the book. Throughout this section, they assume that enterprises use a consistent versioning policy, but not necessarily the same between enterprises, so they classify the strategies as "strict", "flexible", and "loose", and each issue treatment explores how those strategies apply to the issue.

Overall, I was pleased with the content and level of detail in the book. Reading it motivated me to build some sample code in my primary application server, which led me down some very interesting paths and eventual discoveries. Although this led me to discover one minor point where the book content was disputable (mixing two different addressing specs), it led me to appreciate even more how complex the landscape is, which is probably why Thomas Erl saw the need to share the writing load for this latest volume in his series.