Last week we enumerated a pragmatic approach for designing the interactions between clients and services in a Web-Oriented Architecture, which we called WOA/Client. Some of the initial feedback was that this was too high-level a description to be directly useful by the practitioners on the ground that are actively building heterogeneous SOAs and I agree. Fortunately, the intent here is to enumerate each pattern in detail with working examples. And starting with this post, we'll begin delving into as many of the core patterns of WOA/Client as we can.
The work here is a reflection of the distinct trend that software construction on the Web has become more and more about the assembly of distributed clients and services that were originally designed and built separately, yet must work together in harmony. And while service design itself is an very important discipline, increasingly the design of the seams -- particularly on the client side -- will be a far more common engineering practice since the number of individually created and situated client implementations in a heterogeneous SOA -- and the Web's single Global SOA -- can be extremely large compared to more traditional point-to-point client/service integration scenarios. In other words, on the Web, one service might have a dozen, a hundred, or even thousands of unique client implementations running against it. This points to Web-oriented client design and development as a major emerging practice that needs useful, practical, and high-quality design patterns.
Finally, the process of selecting a service and using it becomes an issue since many service providers simply cannot or will not provide tailoring, customization, or even detailed guarantees of service level quality. We need a design vantage point that recognizes that the Web is a rough-and-tumble run-time environment where one can make no assumptions from moment to moment as to the reliability, security, or performance of client/service interactions. This then is the pragmatic aspect of WOA/Client; the emphasis on simple yet robust service models like REST, common sense techniques that focus on what matters including whether the service is working, closely managing and reducing dependencies directly on parts of the service, how to maintain data integrity when mashed-up data is blended together within the client, and so on.
While the original write-up in The Architecture Journal and the post referenced above were high level descriptions of WOA/Client, my work last year on contract checking clients (for the ill-fated service-description language comparison) laid out some of the early groundwork for what became the WOA/Client approach. But the key to all component-based and service-oriented systems is the contract between the client and service. And this is where the story of WOA/Client begins....
WOA/Client and Web Service Contracts: A Firm Conceptual Grounding
A contract is a mutual agreement between two parties about how they will behave with respect to each other. In engineering situations that are divided up into a client and supplier, the contract summarizes the promises made by supplier as well as the obligations put upon the client. The contract makes it clear what the expectations are on both sides, and if the contract is obeyed by both parties, everything works as planned. The classic real-world example is the overnight package delivery contract: Provide the package to the service before 5:30PM and supply payment (the client obligations), and the package will arrive before 10:30AM the next morning (the promises made by the service). Don't meet your client obligations? Then the service is off the hook for delivering on its promises. Without an explicit contract like this, service interactions become cloudy, uncertain, and ultimately unreliable since no one can be sure who is supposed to do what and when. This uncertainty is particularly true in exception scenarios.
But this is far from a theoretical design discussion. The contract shapes the unpinning of the design of the seams in a service-oriented architecture. It's certainly worth noting that contracts are one of Thomas Erl's essential characteristics of an SOA. Carrying the analogy forward a little, the seams create the entire fabric of a SOA and thus an SOA is only as strong as its weakest seams. Strong, clear contracts that are faithfully embodied in the interactions between client and supplier results in a powerfully resilient, rich, sustainable SOA. The best way to design these interactions? You guessed it: The principles of WOA/Client.
Figure 1: Programatically Checking the Contract Between the Client and the Service
Now, keep in mind, every client/service pairing in the world already has a contract. Sometimes it's explicitly stated in machine-readable form in an SDL (service description language), sometimes it's just in a design document, and quite frequently, it's only in the code or in the developer's head. But there's always a contract, whether it's formally defined in detail, or just assumed by creators of the service and its attendant client implementations. In the formal Web services world today (SOAP and the WS-I profiles), a large part of the contract lives in WSDL, the canonical description language for SOAP-based services. I say part of the contract because the obligations on the client and the promises made by the service can't be completely described in WSDL and it's not designed for this purpose. In fact, you will find that you'll have to augment WSDL with additional contract checks in order to fully capture the spirit of the contract. And if you're using REST, for which there is no generally accepted SDL (and no, hardly anyone is using WSDL 2.0), you have some work to do in order to capture your contract. Because capture it you must, since with WOA/Client you'll usually need to verify it periodically, automatically, and programatically -- though usually not with every interaction.
Why programatically check service contracts at all? Why not just code clients and services optimistically?
This question is the crux of this pattern. In fact, it goes directly to the heart of why we have contracts at all. And that purpose is to make all known expectations-- and assumptions -- explicit between multiple parties. When code is developed by a single party, the agreement between two pieces of code in the system is usually quite clear to them; they are in possession of all the intents, facts, realities, and desired outcomes. As soon as the code for a client or service is developed by two or more different parties, that information must be captured somewhere for both parties to refer to. The captured information becomes the contract between the client(s) and the service and is used for the basis of all subsequent design, development, testing, and troubleshooting. Again, the quality of the contract can range in formality from simple verbal conversations between developers all the way up to a set of formal, machine-readable specifications.
The issue in Web-scale systems is that the world of Web services contracts is presently in a fairly sorry state indeed. Not only is it likely you won't be able to ask more than a few questions from your supplier, but they will very likely be using a Web services model (REST, HTTP, JSON, RSS, Atom, etc.) that has no formal contract at all other than their general-purpose industry specifications. You might even just have an HTML page with some lightly structured, informal description. Though the simplicity of most Web services on the broader Web seems to make their consumption easy in the beginning, there are many pernicious issues that will crop up. This include service upgrades, versioning, deprecation, service failure, and others that you must deal with. And these same issues crop up with each and every service that you access from a client. What's a WOA developer to do?
What's needed is a consistent contract-based Web client approach that's not tied to a specific platform, language, or protocol
The WOA/Client approach says that the contract must be captured in machine-readable form (this can be in code or an checked, external description language.) An important aspect of this approach is that it doesn't over-prescribe how this is done, only that is must be done. In the contract, the client must meet its obligations so that the service will do what it promises. On the server-side -- though the service-side design patterns are specifically outside the scope of WOA/Client -- the sevice nevertheless has a set of percieved and/or stated promises that it makes to the client (where it's located, what protocol it uses, what operations it supports, what data types it accepts and returns, what exceptions it throws and when, etc.) If offered by the service, the client must check these, else more guerilla programming style methods must be used. For SOAP, this means checking the WSDL as well as some additional verification as appropriate. For REST, this means checking the reprentational state as expected from the server. For things like JSON, it might mean writing a contract-check that verifies the structure of returned messages.
Sidenote: Sam Ruby's recent comments about the importance of the hyperlink with respect to WOA is significant and highlights an important difference between REST and SOAP. SOAP allows the use of URIs, while REST resources are identified and fundamentally defined by them. Also, read this article in the SOA Web Services Journal about the URL as the fundamental unit of thought in modern Web software.
Non-Technical Constraints
For more background on some of the design tensions in composite applications, read
an article on how the intangible aspects of mashups and composite software matters most.
How often a client checks its contract is entirely up to the individual requirements of the WOA/Client. Many systems cannot tolerate full contract checks for each operation and it's probably overkill anyway. Instead, checking of the contract can often be done in parallel instead of inline, and on a periodic, asynchronous basis as well.
The goal: Detecting changes to or failures in the service's functionality -- as specified in the contract -- and positively degrading operation of the client. As you may recall, WOA/Client recommends graceful degradation of the client in the face of contractual failures of the service. A software application depending on a failed service located on the Web should operate as meaningfully as possible until the depended upon service returns to compliance with the contract (or the client is changed or upgraded.) Uncertain operation is the practical reality of Web-based systems today and deliberate planning for this reality ensures the highest quality, most satisfying results in application experience.
OK, I recognize the Design by Contract precepts in this pattern, but isn't checking supposed to be turned off in deployed use?
WOA/Client emphasis on explicit contracts in code or a machine-readable description language is indeed based on Bertrand Meyer's Design by Contract approach. Design by Contract is the most effective way to mediate the interactions between two pieces of software that were developed separately and the creators of WSDL seemed to have understood this. But the reality is that most Web services stacks today don't check the contract constantly or even at all, it's mostly done at design-time today. And in most Design by Contract packages, such as Gary Leavens' terrific Java Modeling Language, contract checking is designed to be turned off once testing is complete since you know that the clients and suppliers are meeting their obligations and there's no need to check any further. Unfortunately, this scenario only works in situations where both the client and supplier are under your direct control. You might even be able to get away with this in enterprise SOA situations, but you won't out on the Web. While you service supplier might be under agreement to tell you when they change it, the reality is that anything can and probably will happen, particularly with situational softwae such as mashups. As long as the supplier can change any aspect of the service at any time with notification, you must have a run-time contract checking strategy.
And all of this does depends to some extent on your level of control in the client/supplier relationship. For example, informal applications like mashups typically won't have any work done on the service-level agreements nor will the result require more than a light application of WOA/Client patterns. More serious distributed business applications on the Web will require full-strength WOA/Client to meet their expectations, and this will be easier because of the higher (but never complete) control over your suppliers. Either way, using this pattern and the other WOA/Client patterns will raise the resiliency, maintainability, and quality of your composite application or mashup in a consistent, repeatable way.
The WOA/Client Run-Time Web Service Contract Checking Pattern
Pattern Formula
- A Machine-Readable Contract: Identify a machine readable contract, even if it's just client code that checks the message format for expect structure and value types and ranges. For SOAP, use the WSDL supplied with the service, preferably an online version provided by the supplier that is kept up to date. For REST, check the current state representation against what was supplied. XML contracts are often easily checked by XPath statements (see example below), but your local programming environment and architectural constraints will guide what's possible. But however the service contract is checked, do it consistently and clearly.
- Check the Contract: The service can change at any time, intentionally or otherwise, it must be checked. Important: Only check the part of the contract your client cares about, changes must be tolerated that don't break your client. Don't forget about checking endpoint, protocol, response time, and other aspects if they matter to you.
- Degrade Gracefully and Granularly: Just because a portion of the contract changes, the service may still provide some information of utility. Though traditional Design by Contract says that all bets are off completely if any part of the contract breaks, this is not practical or realistic if contract checking reports that a particular operation or portion of returned data is still valid and correct. Be pragmatic, gracefully degrade the features that depend on the failed parts, and keep the level of functionality as high as the broken contract allows.
The following is a brief tour of a SOAP-based WOA/Client written in Ruby. While this might seem antithetical to followers of REST, I clearly indicated in my original write-up that WOA must accept any service model based on HTTP, yet prefer and recommend the ones that go most with the 'grain' of the Web. I will redo this example in REST as soon as possible. And just as importantly, this pattern must be easy and simple to implement in the browser for mashup development, and I'm preparing an example of this as well.
Tour of Contract Checking WOA/Client
I have created a very rudimentary order processing SOAP service (SOAP endpoint here, WSDL here) for the purpose of demonstration only. The order service offers two operations, placeOrder(Order), and getOrderStatus(orderID):Order. The first operation takes an order, and if the order number is unique, accepts it and stores it on the server for processing. The second operation takes an orderID and returns the XML for the originally placed order. You can see a list of all currently placed orders here on this Web page.
While the order service itself is written in C# and hosted on IIS/.NET, to show the issues with heterogeneous SOA and Web 2.0 open platform-oriented software in general, the client was instead developed in Ruby. The client carries out the majority of the WOA/Client patterns that apply to it, including expecting constant change, using bare data representation (probably too bare, but that can be debated), agnostic to protocol/platform/language, extreme loose coupling, and deep resilience. In fact, this Ruby client will NOT break as long as no changes are made to the part of the contract it cares about. The order service can evolve in any direction, adding, changing, and dropping operations, data fields, data types, etc. And as long as none of the changes affects the specific paths the client cares about, the client will continue to function correctly in the face of even extreme changes to the service over time. Note that this client is simplistic and presently checks the contract every time an order is placed. Better heuristics for the frequency of contract checking could and should be used and are not shown here.
The full source code for the Ruby WOA/Client can be found here.
To use the Ruby client and see how it works, just download it and remove the .txt extension. Also make sure you've installed the latest version of Ruby from the RubyForge. It's one click and easy.
To run the client and place an order, type the following on the command-line, replacing **orderID** with an order number not already listed on the order listing page:
ruby oc.rb http://hinchcliffe.org/order.asmx?WSDL **orderID** 1 19.95 2006-08-12T12:14:37
Let's take a tour of the individual pieces of the Ruby WOA/Client and see how the contract checking actually works.
First, the Ruby client pulls a machine readable description of the contract from a remote server location (to ensure it's the freshest):
Pull the current, live service-contract for the service
# Fetch the WSDL at the URL provided
puts "Get the Machine Readable Service Description"
h = Net::HTTP.new('hinchcliffe.org', 80)
resp, sd = h.get('/order.asmx?WSDL', nil )
Then, the client uses XPath expressions to drill down into the contract to see if the part the client cares about has changed. There are a lot of checks, and so I'll only include the first one, you can consult the source code for the rest:
Example of using XPath to check the validity of the service contract
# We want to place an order, and we know it's WSDL, so let's check the contract
# Is there an Order Service described?
q = XPath.first( doc, "/wsdl:definitions/wsdl:service/@name[.='OrderService']")
if q == nil
raise "UNACCEPTABLE CONTRACT CHANGE: No OrderService present"
end
In the code above, each check is done by attempting to travel from the root of the WSDL down to the required elements. This ensures there is structural integrity in the contract and that pieces have been "moved" from one area to the other. And yes, for now, there is still now considerable art in this approach and engineering judgement must be used to decide how thorough, complete, or consistent the contract checking must be done. For most purposes however, the general guidelines of checking operations, parameters, and simple/complex types is usually adequate.
I will further explore the nuances and decision points in this pattern when the REST version of this pattern is depicted in an upcoming post. And as always, please leave your comments, suggestions, and criticisms below.