What Belongs in a Service Contract?

Service-Oriented Architecture (SOA) has finally turned a corner: companies are shifting from the tentative first steps of Service enabling a few systems here and there to strategic SOA rollouts of all sizes that now have the blessing of senior management in the IT departments, and sometimes business executives themselves. In the hundreds of conversations that ZapThink has had in the past year, we have recognized a clear, decisive pattern of organizations moving toward SOA and away from the tightly-coupled, brittle integration approaches of yesterday. We’re no longer getting questions about the “whats” or “whys” of SOA, but rather the “hows” and “whens.” In fact, companies no longer discuss whether or not to embark on an SOA initiative. The eventual move to SOA is fast becoming a fait accompli.

In the midst of this decisive move toward SOA, we are now starting to get more difficult, tactical questions about how to implement SOA. Some questions are organizational in nature, while many others are technical. The questions generally focus on the core issues of SOA. We’re not seeing as much emphasis on technical zingers such as the best way to set up complicated transaction-based systems with million message-per-second throughput, but rather some of the simplest questions one could ask about SOA. Many questions center on how to build a Service. In particular, the question many architects are asking us now is what exactly goes in the Service contract.

The Service Contract: The Most Important Metadata for SOA
The most basic interaction in SOA is between Service providers and Service consumers. For each interaction between these two parties, one provides some combination of data and functionality and the other consumes it. Before the provider can provide whatever the Service offers, however, the two parties must come to an agreement, or contract, that specifies the details of the Service the provider is performing. As with any good legal contract, the two parties are at “arm’s length” — that is, they remain independent parties who don’t get to mess around in each other’s business, except as the contract explicitly provides for. Essentially, the contract loosely couples the relationship between the provider and the consumer.

It’s important to note, however, that there are two different senses of contract in play here. First, there is the legal agreement between two business entities, and second, there is the technical relationship between the parties that aim to work with each other. In order to simplify this technical relationship, we can use an abstraction that represents some simplification of how the Services work as well as the parties in the contract. Just as legal contracts are documents that outline a set of enforceable rules and agreements written in a language that both parties can understand, in IT we need to define a contract that stipulates IT “rules of engagement” in a standardized manner that both the consumer and provider can understand. Such information should also appear in a document external to each participant that provides the information each participant needs to interact with the other.

Such contracts are the key to loose coupling, which goes to the heart of SOA. Loose coupling mandates that two interacting parties should have as little information as possible necessary to govern their relationship. Furthermore, the entire reason why we want to loosely couple software is so that we can independently create and control each component of the IT environment. The way in which we choose to make loose coupling a reality is by implementing contracted interfaces on systems, and making sure that we enforce those contracted relationships while allowing each party to independently change how they implement the contract.

Contracts and Policies
So, given that the contract is key to making Services work, what exactly goes into that Service contract? Just as legal contracts make for solid business relationships, software contracts make for solid, loosely coupled distributed computing. Here’s what goes into a contract — the kind that computers, rather than people, need to understand:

  • Contracts should describe functional requirements, that is, what a provider will give to any consumer that chooses to abide by the terms of the contract. The contract should define what functionality the provider provides, what data it will return, or typically some combination of the two.
  • Contracts must also specify nonfunctional requirements that detail not what the Service does, but the way in which it goes about its business. This includes information both about the responsibility of the providers for providing their functionality and/or data as well as the expected responsibilities of the consumers of that information and what they will need to provide in return, such as availability, security, and other quality of service considerations.
  • Contracts also specify the rules of engagement between consumers and providers, known as policies, that govern who can access a provider, what security procedures the participants must follow, and any other rules that apply to the exchange.

A contract is an expression of visible aspects of Service behavior, and so what contracts never include are the data that providers and consumers actually exchange, or any specifics about how a provider or a consumer will go about meeting the requirements of the contract. In addition, since consumers vary just as much as providers, there might be multiple contracts for a single Service. Another point of clarity is the difference between contract and policy. The definitions of these terms can vary from one company to another, but a general way of understanding the difference is that a policy is a set of conditions that can apply to any number of contracts, from none of them to all of them. For example, a policy might state that all interactions with Services must be SSL-secured, and that policy would then apply to all Service contracts in an organization.

Why WSDL is Not Enough

At the core of all Web Service contracts is the Web Services Definition Language (WSDL), which forms the basic contract for a Service provider, identifying that Service as a Web Service. However, in many ways WSDL is insufficient to describe all the requirements for a contract. First of all, WSDL only defines a basic set of functional requirements for Services, specifically as they apply to Web Services. WSDL is not sufficient for defining non-functional requirements such as security, transactionality, process, commerce, reliability, and service level requirements for a Service, nor does it even come close to defining the semantic requirements for the data a Service actually produce. Therefore, Service contracts require more than just WSDL.

Ideally, there would be a universal Service contract definition language that would include the description of Service semantics, the definition of Service capabilities and constraints, and an interaction model for both data and behavior. However, no such single language exists! Instead, there are a series of additional specifications that augment WSDL now in development that seek to add to the richness of Service contracts, but do so in a piecemeal fashion.

At the forefront of these contract-related specifications are policy specs such as WS-Policy. WS-Policy doesn’t provide the actual semantics for defining policies, but rather a generalized container for specifying a range of policy considerations. Therefore, we need additional specifications like WS-Security, Web Services Business Process Execution Language (WS-BPEL), Web Services Choreography Description Language (WS-CDL), Web Service Level Agreements (WSLA), and Web Service Offerings Language (WSOL) to specify non-functional requirements in greater detail. Also on the horizon are specifications like the Ontology Web Language for Services (OWL-S) that aim to provide a more complete, rich language for defining Service contracts.

You don’t have to wait for these specifications to be ready to build perfectly good Service contracts, however. In the meantime, you’ll need to specify contract metadata in whatever format providers and consumers can understand. Here’s a set of steps we recommend for companies going through the Service contract definition process:

  • First, Define the Service
    • Identify what value the Service provides to prospective consumers
    • Describe the functionality of the Service
    • Delineate quality of service and applicability constraints
    • Define the constraints on the types of consumers or other consumption requirements
  • Next, define how to consume the Service
    • Define message and semantic formats for requests
    • Identify conditions for particular outcomes and behaviors
    • Determine the flow of processes and activities and steps leading to outcomes
  • Finally, define how Services will interact
    • Define how consumers will communicate with the Service
    • Describe acceptable communication protocols
    • Decide on the appropriate invocation style (request/response, notification, event-driven)
    • Set your latency expectations

Complete these steps and you’ll be in good shape to build loosely-coupled Services based on well-defined contracts.

The ZapThink Take
Regardless of the specifications, it’s clear that companies are now grappling with how to create Service contracts. The fact that the specifications are in flux is an important indicator of how nascent SOA is. However, you don’t need to wait for all these rich metadata specifications to fall into place to build Service contracts. In fact, one of the most important activities that a company can do is to define their contracts and policies in a language that humans can understand.

If people can focus on developing contracts instead of code, we’ve already made significant progress toward building loosely-coupled systems. The next step is then to encode those contracts and policies to make the Services actually work. The choice of metadata specification and semantics to do so will reflect the decisions you’ve already made as far as what goes in the contract.

Remember that a contract is nothing more than metadata that describe how parties will interact, and a policy is also metadata that describe the conditions under which those parties are entitled to engage in an interaction. As a result, it’s possible for an SOA implementation to respond to changes in policies and contracts without the need for more tightly coupled, inflexible programming–essentially, change the policy, adjust the contract, and the consumers and providers simply follow the amended contract. This is the vision of SOA in action.