Contract pliability is one of the things I'm looking forward to experimenting with when all the service descriptions are written for our survey. Particularly when we have both REST and and SOAP services and we then make some contract changes that technically shouldn't affect existing clients. Seeing how well the clients withstand the changes will be extremely interesting and hopefully revealing. This is one area we're anticipating we'll learn the most about how service description languages (SDLs) assist clients in dealing with a service over a sustained period of time. In fact, understanding how an SDL encourages suppleness and the graceful evolution of a web service is a primary goal of this effort.
Note: The Java, C#, and Ruby comparison client source code is at the bottom of this post. All three clients are identical in function as precisely as it was possible for me to make them.
I've had a few folks comment that checking for contract changes shouldn't be required. Certain schools of thought believe that if a service changes its contract, the new version should be deployed at a new endpoint and the existing service remain in place and scheduled for eventual phase out. IMHO, this is only a good idea in certain circumstances for SOAP services and is rarely, if ever, a good idea for REST.
There are at least two reasons why you'd want to change a web service contract in-place. One: Services will inevitably change, especially ones that are successful and have many clients. Constantly moving these services to new endpoints whenever a fix or improvement is made is ultimately impractical and disruptive. And largely unnecessary with open-ended contracts and properly modified services. Two: Well-defined endpoints are important in their own right, particularly with REST, to make sure systems stay in communication and to reflect the fact that protocols like REST identify universally addressed resources and not invocation points. A good model to think of is the Internet name server, with two or three endpoints usually identified and which never change to ensure that name resolution services are easy to find and aren't subsequently lost.
Figure 1: Well-Designed Web Services/Contracts Promote Loose Coupling and Service Evolution
For those of you who may just be joining us, keep in mind that the worldview of SDLs we're using for the comparison is biased towards highly heterogenous environments. Not only does that create the most extreme service conditions you will find inside or outside your firewall, it makes sure that SDLs properly deal with worst case situations instead of ideal situations. From this, we can identify the most robust and practical model for service description.
Note that I don't have many issues with the WSDL/SOAP combo when they're used in truly homogenous environements and there's little chance they will be used by clients outside someone's control. Unfortunately, the world is certainly trending away from this narrow view of siloed services. Web services are increasingly becoming part of strongly federated service-oriented architectures (SOAs), enterprise service buses (ESBs), and IT Infrastructure Libraries (ITIL) that cross organization, political, geographic, and technological boundaries.
And I'm certainly not alone in the burgeoning realization that the (necessarily) naive view of web services that emerged in 2000 has evolved tremendously since then, and our assumptions and requirements have evolved along with it. Jeff Schneider's recent post about about The WSDL is the Offshore Contract is just one tiny example of the continued evolution of web services thinking and its implications.
In that vein, a fascinating new paper on this subject emerged from HP last month and has been getting a fair amount of blog play recently. I read it over the weekend at the urging of IONA's Eric Newcomer and it's quite a detailed send up of JAX-RPC, the current Java SOAP stack. What is fascinating is where the criticism is levelled, and it's not just at JAX-RPC. The paper eschews the RPC-centric view that JAX-RPC encourages as "fundamentally flawed" in world headed directly towards loosely coupled XML messaging. Authors Steve Loughran and Edmund Smith go on to enumerate a very impressively researched list of exactly why WSDL and XML Schemas are the wrong format for web service description, particularely when combined with a method invocation model like JAX-RPC. They classify the problems uncovered as various forms of the Object to XML (O/X) mapping mismatch.
It's worth going into the details of their analysis since our SDL comparison should use their specific observations to validate the features of the SDLs in the list as the comparison goes along. I've paraphrased some of the flaws they've enumerated to be less Java-centric when approriate. Here's what Steve and Edmund specifically have to say is wrong with the view of web service interaction represented by the collaboration of JAX-RPC/WSDL/XSD/SOAP:
| Fundamental Flaws of JAX-RPC |
Summary |
| 1) Binding XML Elements to Classes |
It's almost impossible to accurately represent an XSD type hierarchy in most programming language type hierarchies. |
| 2) Mapping XML Names to Language Identifiers |
Avoiding the keywords of even your typical OO programming languages can be a challenge. |
| 3) Enumeration Mapping Is Brittle |
Changes to enumerations cause subtle defects in both client and service code. Reserved words in the enumeration also can break things. |
| 4) Programming Languages Have Unportable Types |
This is a specific criticism of contract-last development of web services. Unportable types like DataSet, Hashtable, and others don't make sense on the interface of interoperable services. Even something as simple as datetimes have significant problems between well known web service stacks. |
| 5) Serializing Graphs of Objects Is Problematic, If Not Broken |
XML is a hierarchical structure and can only describe lists and trees. Object graphs can be cyclic. This causes a litany of issues when mapping between OO<->XML. |
| 6) XML Metadata and Namespaces |
There is no reliable way to map between OO constructs and XML namespaces without it being contrived. |
| 7) Message Validation Isn't Performed |
Contract checking of messages generally isn't done either at the client or the service. This optimistic view of interoperability will cause problems. |
| 8) Inadequate Mixing of XML and Serialized Data |
It's easy for an XML message to "sail off the edge of the world" when mapping from XML to OO. |
| 9) Fault Processing is Platform Dependent
|
Fault handling in OO web services stacks tend to be representations of the programming languages exception structure instead of implementation and platform independent fault information. |
Figure 2: Loughran and Smith's OO-XML Mapping Issues for SOAP Web Services
These points generally mesh fairly well with the position that XML itself should be the abstraction level a developer uses when interacting with services. Unlike the difficulty often involved with storing or retrievng data in a SQL database from a programming language even today, direct interaction with XML from a programming language is relatively straightforward at this point, and improving all the time. As the loosely coupled WSDL/SOAP client showed from my last post, contract checking and service invocation using bare XML without a SOAP stack is quite easy to do properly in a fairly compact amount of readable code.
As for the actual SDL comparison, our construction of the WSDL 1.1 clients is now complete. I did update the C# WSDL client to check if any unexpected mustUnderstand attributes are present in the service contract. This was an important and obvious oversight. Then I rolled the contract checks into Java and Ruby versions of the SOAP client.
Everything done so far with the SDL comparison can be found here:
Next up is our SSDL description for the
Order Service. I've contacted Savas Parastatidis and Jim Webber to make sure I use SSDL correctly and we'll start constructing clients from it once we have a good SSDL description for the Order Service worked out. I will probably post a more detailed tour soon of how contract checking is performed.
Technorati: Enterprise Architecture, Computers and Internet, Programming, Web Services