Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

How to write a service contract

In this second of a two-part column, Preston Gralla looks at what should go into a service contract and how to draw one up.

A new, emerging Web services and SOA concept -- service contracts -- may ultimately become key to more widespread...

usage of the technologies between business partners. It's not yet widely used, but there are those who say that most Web services will ultimately involve a service contract when the Web service is between business partners, rather than for internal users in an enterprise. In this second part of a two-part column, we'll look at what should go into such a contract and how to draw one up.

What's in a contract?
If you haven't yet heard about Web services and SOA contracts, keep in mind that they are not legal documents. Rather, a service contract outlines a set of technical data, and often business information as well. The contract is between whoever is providing the Web service, and whoever is consuming the Web service. It provides details about the service being created by the provider. In creating the contract, both sides know what will be provided and required by each, possibly before any coding is actually done.

That may sound rather vague, but in fact, some very concrete information needs to be put into the contract. To start off with, the contract specifically defines what service the provider will supply, as well as the data -- if any -- the provider will supply. This is the overarching reason for the contract, and needs to be spelled out clearly; if things go awry here, there will almost certainly be problems down the road.

Beyond defining the services and data that the provider will supply, the contract needs to detail how exactly those services and data will be provided. This part of the contract is a two-sided conversation; it needs to detail not only how the service will be provided, but also what the consumers will provide in return for that service.

The contract also outlines the policies that each side agrees to with regard to the service -- who can access the service, what security rules and procedures must be followed, and so on.

Miko Matsumura, vice president of technology and standards for Infravio, differentiates between "low-level" contracts and "high-level" contracts. A low-level contract, he says, would govern something like a Microsoft .NET Indigo services stack and express how, on the lowest level, communication takes place. This kind of contract, he says, is not particularly vital. The higher-level contract has details such as service delivery preferences and service level agreements, and often has business implications.

What's particularly beneficial about drawing up these high-level contracts, says Matsumura, is that a provider can draw up a single, boilerplate contract for a service it will provide to multiple partners, and can then customize each contract as needed. This cookie-cutter approach is a tremendous time-saver, he notes, and makes it far easier for providers to build a business around providing services.

How to draw up a contract
The main notion behind a contract, says Matsumura, is that the contract configures metadata, and that metadata is then deployed against a running service. Matsumura says that there are two primary approaches to drawing up a contract -- a configuration-based approach, and a registry-based approach. A configuration-based approach is favored by developers, and in it, metadata is put into a deployment descriptor.

Matsumura says that Infravio favors, instead, a registry-based approach, which unifies the process of creating contracts by putting all the information into one large metadata repository. A business user, not a developer, can then go into the repository, and manipulate the metadata to draw up a contract. This requires a metadata management system, as well as a browser front-end.

Infravio has recently released a tool for doing just that, its X-Registry Platform Version 5. A new function in the platform, called Service Delivery Contracts, is designed to allow contracts to be drawn up more easily.

No matter what approach to drawing up contracts is chosen, it's a good idea to follow a simple, logical, multi-step process in creating a contract, as outlined by Ronald Schmelzer, senior analyst with ZapThink in his article What belongs in a service contract?.

He recommends first defining the service, including the value the service provides, the service's functionality, the quality of service and any constraints on the consumption of the service.

Next, he says to define how the service will be consumed, including defining the message and semantic formats for requests, identifying conditions for outcomes and behaviors, and determining the flow of processes and activities.

Finally, he says to define how the services will interact, including how consumers will communicate with the service, what the acceptable communications protocols are, what the appropriate invocation style is, and the latency expectations.

When you're done, you should have a solid contract.

The future of service contracts
The concept of service contracts is still relatively new, and even its adherents say that they are still rarely used. But many people expect that eventually they will become commonplace when a Web service or SOA involves business partners. Contracts may even ultimately be used within an enterprise; for example, between business units or departments.

So even if you're not using contracts today, be prepared, because you may be called upon to draw one up, or sign one, in the not-too-distant future.

About the Author

Preston Gralla is an expert on Web services and the author of more than 30 books, including How the Internet Works. He can be reached at preston@gralla.com.

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.