Tracking change and innovation in the enterprise software development community
QCon London 2010!
March 10-12, 100
Speakers, 80 sessions,
"THE" team leads and,
architects conference.
Scaling Scrum
in the enterprise?
ScrumWorks Pro
can help.
Start a trial today
Free Book Offer
SOA Demystified
$40 Value
Posted by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, L. Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley on Nov 06, 2009
Today we introduce the book “Web Service Contract Design and Versioning for SOA” by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, L. Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley. More exactly, chapters 20, 21, and 22 of the book addressing the issues related to service contract versioning.
Free $40 SOA Demystified Book Offer
Right Collaboration Architecture Drives Business Transformation
Understand and Align BPM, SOA, and Lean Six Sigma: 43 page IBM Redguide
Restful BPM, Pragmatic SOA, Mashups, Avoiding Failure: SOA track @ QCon London in March
Visit SOA Appliance Comparison Site
*Video Usage Model Tutorials
*Comparison to IBM DataPower X150
*Performance Benchmarks/Webinars
*Replace DataPower Program
FREE 1:1 Swap & Migration Services
Web services in a SOA-based solution need detailed, technical contracts which clearly specify what each service is meant to do and how is to be used. Since services are subject to change over time, the contract designers need to make sure service consumers use the appropriate variant of the contract, problem solved through versioning.
In this chapter, the authors present the basic concepts and terminology used in versioning, compatibility issues to be addressed, how to use version identifiers, and several versioning strategies one could choose from.
Since a web service contract can be made up of multiple documents - WSDL definitions, XML Schema definitions, WS-Policy definitions – versioning should apply to all documents that change when the contract changes. Usually, the WSDL versioning is considered, but it is possible changes to appear in XML Schema definitions too, so they also need to be versioned.
There are 4 fundamental types of changes that need to be considered: backward compatible, forward compatible, compatible and incompatible. This section explains each type of change accompanied by examples.
The next sections present the most common versions identifiers used and versioning strategies. Three strategies are detailed:
- Strict – Any compatible or incompatible changes result in a new version of
the service contract. This approach does not support backwards or forwards
compatibility.- Flexible – Any incompatible change results in a new version of the service contract
and the contract is designed to support backwards compatibility but not forwards
compatibility.- Loose – Any incompatible change results in a new version of the service contract
and the contract is designed to support backwards compatibility and forwards
compatibility.
In this chapter, the authors deal with versioning of WSDL definition documents using the “significance of change” approach and the documentation element. Beside versioning the entire document, the book contains examples of versioning the operations definitions, the port type definitions, and the concrete descriptions.
The XML Schema definitions contained by a service contract represent the basis for input, output and fault messages exchanged during service use. As a consequence, the authors consider that XML Schema definitions are most often subject to change and in need of versioning.
The chapter explains what XML Schema components are, their content sets, and the effects of adding/removing/renaming/modifying components and their relationship to versions. The authors also explain how changes of the XML Schema target namespaces affect the WSDL target namespaces and how to apply strict, flexible and loose versioning in such cases.
These chapters are excerpted from the book Web Service Contract Design and Versioning for SOA, authored by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost and James Pasley, published Sept. 2008 by Prentice Hall Professional as part of The Prentice Hall Service-Oriented Computing Series from Thomas Erl, ISBN 013613517X, Copyright 2009 SOA Systems Inc. For more info, please visit informit.com/soa or soabooks.com
This book is great and has everything in it for everybody who is planning to create XML-based services of whatever flavour. I consider it a must-read (at least the core chapters)
Sadly, the number of pages accurately reflects the apalling complexity of XML-Schema + WSDL + versioning. I thank the authors for nailing down all aspects of this terrible subject.
Personally, I buried my optimism about the ambitions of developers to get a grip on all that. Ask anyone about the "unique particle rule". Or try to explain why naive XML-Schema-based web services are a very tight coupling, so much in conflict with the brainwashing SOA propaganda that is running for years now.
I see naive webservice/schema implementations all over the place, because those are easy to find with Google (that's how we learn new technology these days!), quick to implement, and they get the job done at least for short term. I am tired of arguing against this.
I take it from the description and the comment that there isn't a section on RESTful services and how to properly version them?
No, it's about WS.
That's a real good question. How do you handle versioning in REST? Sure enough you can version "resources", but I am not sure that's what you are looking for.
You should start by defining what you mean by a "RESTful" "Service". There is no notion of service in Roy's REST, let alone versioning.
I would actually argue that since the interface to a resource is uniform, why would you even need to version that interface? That sounds like an oxymoron.
The interface is what's uniform, not the resource. Inbound and outbound representation is bound to change over time and if a service needs to be backwards compatible, like mine does, you have to consider it.
I handle REST versioning via content negotiation with a version embedded in the mime-type. I came to this solution after doing a lot of Googling. There wasn't a clear winner as far as a standard stating "thou shalt do this". Which is why I asked the question in the first place. There are probably other ways, but this one seemed most clear and maintainable to me.
Dave:
yes, the only problem with that approach is the combinatory problem of Mime Types x Versions x Who knows what else. The content negotiation was never designed to handle versioning.
Unfortunately, since REST couples access with identity, you are out of luck, you are stuck with this kludge. One day you will appreciate the ability to assign a particular version to a single endpoint, independent of any resource identity.
yes, the only problem with that approach is the combinatory problem of Mime Types x Versions x Who knows what else.
As opposed to interface versioning x verions x who knows what else (read policies, protocols)?
I need to add that the chapters about XML Schema design and versioning are equally useful for all kinds of interfaces, which carry XML-Schema-based content.
I ask any colleague who is about to design a schema to read those chapters. It is the completest and most concise source I know.
I like the book, however I find the subject disgusting :-)
Hello David.
Yes, that is a way I've seen in several discussions, and it sees has some drawbacks.
But Jean-Jacques is right in the "RESTful" "Service" sense of what you are looking for. A service has some particularities, that will provide enough for a long discussion on how a Service can be made RESTful.
The most common confusion is that service consumption is just an RPC call. For that part, a RESTFul service is then an RPC call that is made in a RESTful way? We have problems there since REST is not about RPC. Actually, many so called RESTFul API were discredited as such by Roy himself because they were plain RPC calls.
Now, if you go the right way, a service being a business functionality that can be consumed sending asynchronous messages to it with documents, then we hit another wall there, since REST in its HTTP implementation, uses actual operations that are synchronous.
If you solve those conceptual issues, then you may be able to apply the considerations of the book about versioning, or you may find out REST may manage that easier due to hypermedia state control.
Cheers
William Martinez
As far as I understand the -- thorough -- discussion in the given chapters, adding an optional element (minOccurs="0") is generally considered backward compatible. This surely is correct for messages sent _to_ the provider of the web service. But what if this element is part of a message (response) sent from the provider to the "client". Then an additional element might be incompatible, if the client can not handle additional elements. And many frameworks, especially those mapping the message to objects, have problems with additional content.
other thing that this book doesn't consider is the transport protocol, if i use jms the "consumer" role is different and compatibility changes too.
Brian Marick takes us through a quick tour of the most important values and challenges to adopting Agile successfully (they aren't the typical challenges and values we hear in the community).
The line between development and architecture is tricky. Does it exist at all? Is an ivory tower actually needed? There's a balance in the middle, but how do you move from developer to architect?
The word 'authority' sometimes produces an allergic response in hard-line agilists. Freedom and authority – both are bad if misused and both are good if used in right spirit for a noble cause.
"Getting Started with Grails" brings you up to speed on this modern web framework. Companies as varied as LinkedIn, Wired, and Taco Bell are all using Grails. Are you ready to get started as well?
Those familiar with only ITIL V2 often scoff at the thought that ITIL could serve as a governance framework for SOA. With ITIL V3, the focus of the framework shifted towards service-orientation.
SpringSource CTO Adrian Colyer discusses AspectJ, SpringSource's dm Server and tc Server products, OSGi and Scrum.
Heroku's Adam Wiggins talks about Rails, Background Jobs, Add-Ons, Ruby, and how Heroku manages to work around Ruby's inefficiencies using Erlang and other languages.
For Grady Booch the foundation of a good architecture is patterns, SOA being just one of many patterns. In this Second Life presentation, Booch attempts to bring more clarity on what architecture is.
11 comments
Watch Thread Reply