Anatomy of a Web Service Contract
- 4.1 What is a Web Service Contract?
- 4.2 The Parts of a Web Service Contract
- 4.3 Technologies Used to Create Web Service Contracts
- 4.4 Guidelines for Using Web Service Contract Technologies
What is a Web Service Contract?
The Parts of a Web Service Contract
Technologies Used to Create Web Service Contracts
Guidelines for Using Web Service Contract Technologies
Web service contracts can range in content, depth, and complexity. To fully appreciate the intricacies and design options of how Web service contracts can be structured, we first need to decompose this structure in order to understand its individual parts and the mechanics that make these parts work together.
The purpose of this chapter is to explain the Web service contract from a conceptual and structural perspective without yet getting into the details of how the contract is actually developed through markup code.
We start exploring contract structure by breaking the contract down into a set of primary parts. This allows us to describe what these parts are, what technologies can be used to create them, and how they can relate to each other. Subsequent chapters will then drill down into each of the mentioned parts and technologies.
4.1 What is a Web Service Contract?
A Web service contract is essentially a collection of metadata that describes various aspects of an underlying software program, including:
- the purpose and function of its operations
- the messages that need to be exchanged in order to engage the operations
- data models used to define the structure of the messages (and associated validation rules used to ensure the integrity of data passed to and from the messages)
- a set of conditions under which the operations are provided
- information about how and where the service can be accessed
Several different and cooperating technologies are required to formally define this metadata, as explained later in the Technologies Used to Create Web Service Contracts section.
Web service contracts are organized into a basic structure that reflects a relatively clear separation of “what,” “how,” and “where” as follows:
- What is the purpose of the service and its capabilities?
- How can the service be accessed?
- Where can the service be accessed?
When potential consumer program designers evaluate a service, they need to know what the service is capable of doing and under what conditions it can carry out its capabilities. If what’s offered is what consumer designers need, then they must be able to determine how and where to access the service.
As illustrated in Figure 4.1, the service contract is organized into sections that individually address these three questions.
Figure 4.1 A Web service contract defines what a service offers and how and where it can be accessed.
In addition to providing flexibility as to how a service can be located and consumed, this clean separation allows different parts of the contract to be owned and developed at different stages of the service delivery lifecycle by different members of a project team.
For example, architects and analysts can focus solely on the “what” part of a service when it is being conceptualized and designed. The “how” and “where” parts don’t usually become relevant until developers actually build and deploy the contract as part of the overall service implementation.
Abstract and Concrete Descriptions
There are formal terms used to represent the three fundamental parts we just covered. As shown in Figure 4.2, the “what” portion of the Web service contract is referred to as the abstract description. This part is essentially responsible for expressing the contract’s public interface (or API).
Figure 4.2 An abstract description establishes the technical interface independent of implementation details. A concrete description adds deployment-specific details about how and where to access a service.
The balance of the Web service contract is represented by the concrete description, providing the implementation and communication details necessary for consumer programs to locate and use the service at runtime.
The concrete description encompasses the previously described “how” and “where” parts. An example of a characteristic that would be considered a “how” part is the wire format and protocol necessary to exchange messages with the service.