Web Cohesion

glue for the programmatic web

Compiled Contract

A Web Service Development Model

Ryan Heaton

16 March 2007

Copyright © Web Cohesion, All Rights Reserved

Abstract

Web service developers have generally been limited to two different development models, each with its own advantages and disadvantages. The “code-first” model provides a familiar environment and a flexible development process, but has historically suffered from impaired interoperability. The “contract-first” development model allows for elevated interoperability, but at the cost of a high entry barrier, a steep learning curve, and a heavy development process.

Compiled contract is a new development model that claims the major benefits of both the code-first and contract-first development approaches. Compiled contract extends upon the code-first development model in that the API is developed and maintained in the source code of the target programming language, retaining the advantages of a familiar environment and a flexible process. With the original source code, the compiled contract model introduces a new compile-time step: a source code engine (called a “contract compiler”) is invoked to produce an unambiguous, fully-documented Web service contract. Interoperability is enforced at compile-time because the process halts if the contract compiler cannot produce a contract that conforms to a widely-established set of interoperability standards. The contract compiler can also facilitate a clean, lightweight development process by automatically packaging the application artifact.

Table of Contents

Abstract
1. Introduction
1.1. Intended Audience
1.2 Status of this Document
1.3. Definition of Terms
2. The Web Service API
2.1. Interoperability
2.2. The Web Service API Agent
2.3. The Contract
3. Code-First vs. Contract-First
3.1 Code-First Development
3.2. Contract-First Development
3.3. Advantages of Code-First Development
3.4 Disadvantages of Code-First Development
3.5 Advantages of Contract-First Development
3.6. Disadvantages of Contract-First Development
3.7. The Development Decision: Code-First or Contract-First?
4. Compiled Contract
4.1. Advantages of Compiled Contract Development
4.2. Disadvantages of Compiled Contract Development
5. Conclusion
Appendix A: Notes and References

1. Introduction

The intention of this document is to formalize the compiled contract approach to Web service development and to examine its advantages and disadvantages, especially as it relates to other development models.

Section 1 establishes a frame for this document in terms of its intended audience, status, and a definition of terms. 

Section 2 describes a Web service API by its major characteristics, emphasizing the contract to which the Web service API is bound. 

Section 3 is a description of the two dominant approaches to Web service development, including an analysis of the advantages and disadvantages of each. 

Section 4 introduces the compiled contract approach to Web service development and discusses its advantages over the other development approaches. 

Section 5 concludes the document. 

1.1. Intended Audience

This document was intended for Web service architects and engineers who are establishing a development framework for publishing a Web service API. It is assumed that readers are familiar with the basic concept of Web services and with the fundamental principles framing the debate between Web service development models.

1.2 Status of this Document

This document is a working draft, and should not be considered final. Other documents may supersede this document.

1.3. Definition of Terms

  • Web service
    A software system designed to support interoperable machine-to-machine interaction over a network.
  • Web service API
    A collection of Web services used to support related functionality for a particular person or organization.
  • Web service definition (WSD)
    A formal, machine-processable specification of a Web service API.
  • Web service definition language (WSDL)
    The programming language used to write a WSD.
  • Web service API Agent
    The executable code that implements a Web service API.
  • Provider
    The person or organization that is responsible for the support and maintenance of a Web service API agent.
  • Interoperability
    The capacity of a Web service API to be consumed by clients of different platforms. Interoperability is measured by more than just the existence of its WSD, as some definitions are more difficult to consume than others, with the level of difficulty varying from platform to platform.
  • Application Container
    A software engine that is responsible for accepting Web service requests, unmarshalling them as calls to the Web service API agent, then marshalling the results of the calls as Web service responses.
  • Integrated Development Environment (IDE)
    A software program that assists developers in writing software. An IDE usually includes a source code editor, a compiler, and other build tools. It often also includes a debugger, support for version control, and refactoring utilities.
  • Code Reflection
    The process of inspecting the abstract constructs of executable code to determine their names and properties. Code reflection is often used by an application container to determine how an agent is to be published as a Web service API.
  • Programming Language Metadata
    The set of attributes (and their associated values) that can be assigned to executable code constructs (such as fields, methods, and classes) through features in the programming language. Programming language metadata is supplied by the developer in source code, is available at runtime through code reflection, and is leveraged by the application container to discover how to publish an agent as a Web service API.
  • Deployment Descriptors
    The configuration files that are needed to describe to the application container how to publish an agent as a Web service API. The deployment descriptors supply the metadata that isn't provided by the programming language metadata.
  • Agent Artifact
    The packaged bundle that consists of the Web service API agent and the deployment descriptors. The agent artifact is what is deployed into an application container.
  • Web service API Contract
    An official and comprehensive description of a Web service API that includes the formal WSD and any other informal, human-oriented documents that are needed to understand the API. It represents the overall description of what is provided. Also referred to as the “Web service contract” or simply the “contract.”
  • Contract Compiler
    A computer program that produces a Web service API contract from source code. The contract compiler contains rules that define how the code will be published as a Web service API when deployed in an application container, and produces a contract that conforms to those rules. Furthermore, the contract compiler must fail if unable to produce a contract that is unambiguous and interoperable according to established standards for interoperability1. The contract compiler should produce any human-oriented documents defining the semantics of the Web service API in addition to the formal WSD. The contract compiler may also do additional work such as creating any necessary deployment descriptors and producing the agent artifact.

2. The Web Service API

A Web service is defined to be "a software system designed to support interoperable machine-to-machine interaction over a network,"2 enabled through the use of platform-neutral specifications and protocols. A Web service API is a collection of Web services used to support related functionality for a particular person or organization (formally referred to as the provider3). It is here important to recognize three main characteristics of a Web service API: interoperability, the agent, and the contract.

2.1. Interoperability

An important purpose of a Web service API is to support a platform-neutral interface to the functionality supported by the provider. Interoperability becomes important to the extent to which this functionality is needed to be made accessible by the widest possible audience, regardless of platform.

Interoperability is facilitated through the use of platform-neutral protocols and specifications described by the contract. Interoperability must be measured by more than just the existence of a valid WSD; regardless of how well a WSD conforms to its specification, some definitions are more difficult to consume than others, and the level of difficulty varies depending on the platform of the consumer. For this reason, interoperability must be measured by how well a Web service API conforms to a common, widely-accepted set of interoperability standards, such as those established by the WS-I Basic Profile.4

2.2. The Web Service API Agent

The Web service API agent is the concrete piece of software, running in an application container and supported by the provider, that executes the functionality provided.5 It is the actual implementation of the Web service API. An important concept in Web service development is that Web service API is independent of the platform on which the agent is implemented.6 It is most often the case that the agent is compiled and maintained in a programming language that contains libraries and other support for Web service development, such as Java7 or C#8, but this fact is irrelevant as long as the agent adheres to the contract.

2.3. The Contract

The Web service API contract is the formal specification of the Web service API. The contract specifies the messages and protocols that are used to access the API (the syntax). The contract also includes a description of when and how the API is to be used and the expectation of its behavior (the semantics).

The syntax of the Web service API can be described in a Web service description (WSD) using the Web service description language (WSDL).9 The WSD describes the API in terms of the request/response messages, the structure of the messages, the supported protocols (e.g. SOAP10, HTTP11, MIME12, etc.), and the location of the services. As much as is possible, the mechanics of the Web service API are formalized by a WSD so as to be machine-processable and enforceable by conformance to the appropriate specifications.

The contract must specify more than the syntax of the API. The WSD can describe how the Web service API is to be invoked, but it generally does not specify when it is to be invoked, or how it is to be used. These aspects are referred to as the semantics of the API13, and must usually be provided in the form of user-level documentation, implicit conventions, verbal interaction, or other forms of human-oriented communication. The semantics of the API provided by the contract supply the consumer of the API with critical information that cannot be supplied by a formal syntax definition. The semantics are also useful to clarify ambiguities and to indicate potential incompatibilities between the contract and the concrete implementation.

The contract is supplied and maintained by the provider, who must consider the cost of supporting and maintaining it. 

3. Code-First vs. Contract-First

When considering the process of developing a Web service API, there are (generally speaking) two opposing models, each with its own advantages and disadvantages. 

3.1 Code-First Development

The “code-first” development model is generally defined by the following steps: 

  1. The API is developed in the source code of the target programming language. 
  2. The source code is compiled to produce executable code.
  3. The executable code is packaged along with the necessary deployment descriptors as the agent artifact.
  4. The agent artifact is deployed into an application container that publishes it as the functional Web service API agent as specified by the deployment descriptors.
  5. The Web service API contract is generated by the application container at runtime as needed.

The “code-first” development model is illustrated in Figure 3-1:

Code-first development

3.2. Contract-First Development

The other approach to Web service API is known as the “contract-first” (sometimes known as “WSDL-first”) development model. The contract-first model it is generally defined by the following steps:

  1. The formal contract is developed in WSDL and enhanced with other human-oriented documentation to describe the semantics. 
  2. The WSD is usually supplied to a code generation engine that generates a set of interfaces in the target programming language. 
  3. The implementation of the Web service API is written in the source code of the target programming language. 
  4. The implementation source code is compiled against any source code interfaces generated from the contract to produce executable code. 
  5. The executable code is packaged along with the necessary deployment descriptors as the agent artifact.
  6. The agent artifact is deployed into an application container that publishes it as the functional Web service API agent as specified by the deployment descriptors. The Web service API contract is also deployed into the application container to be referenced as needed.
  7. Requests for the Web service API contract are answered with the contract developed in step 1. 

The “contract-first” development model is illustrated in Figure 3-2:

Contract-first development

3.3. Advantages of Code-First Development

The advantages of the code-first development model are rooted in the fact that the Web service API is developed and maintained in the source code of a specific programming language. This carries the following benefits:

  1. The entry barrier to Web service development is low and the learning curve is gentle.

    Because development of the Web service API is done in a common programming language, developers don't have to learn the heavy complexities of the Web service specifications and technologies. The burden of expertise in these technologies can be consolidated with the developers of the application container who specialize in knowing the intricacies of Web services. This significantly reduces the time and training cost that the Web service API provider must sustain.

  2. The Web service API can be created, updated, and refactored by leveraging standard tools and Integrated Development Environments (IDEs).

    Developers can maintain the Web service API in an environment with which they are familiar. The capabilities of the IDE can be used to perform common refactoring operations such as renaming parameters, moving files, interfacing with source control, etc.

  3. The Web service API, as defined by the contract, is fixed to its implementation.

    Since the contract is generated at runtime by the application container using the agent artifact, the implementation is never out of sync with the Web service API. This eliminates the potential for confusing deploy-time errors and the possibility of unimplemented methods defined by the contract.

3.4 Disadvantages of Code-First Development

The code-first development model carries some notable disadvantages: 

  1. Interoperability is generally reduced.

    The reduction in interoperability is the result of ambiguities introduced by translating executable code into the language of the Web service API contract. The application container has to make assumptions at runtime about how the executable code is to be translated. Two reasons for the possible loss of interoperability during this translation process are here noted: (1) different platforms make different assumptions about how a contract is to be consumed, and (2) there is generally no enforcement of conformance to common, widely-accepted interoperability standards.

  2. User-level documentation is inconvenient to maintain.

    The application container is limited to the piece of the contract that describes the syntax of the Web service API. The semantics have to be described in user-level documentation maintained in a separate location within the source code base, and then packaged appropriately in the agent artifact. The fact that these documents are maintained separately from the implementation source code makes maintenance inconvenient, if not burdensome. When the documents are not maintained in step with the implementation, the semantics of the contract could be inaccurate.

  3. The view of the Web service API is often narrow.

    It is difficult for the application container to determine how the Web services defined by a Web service API relate to each other. This results in the application container presenting a very narrow view of the entire Web service API, giving no context in which to place a given Web service.14 For example, when the application container services a request for the WSD of a specific service, it often presents a WSD that contains only the elements of the Web service API that are provided by that service, excluding the elements of the other services that support the API.

  4. The code-first model is limited by the level of programming language support for metadata.

    In order for the application container to be able to publish the executable code as a Web service API, it has to be supplied with certain metadata to describe how the code is to be published. Normally, the metadata is supplied through features of the programming language like code reflection and language metadata. What cannot be supplied via features of the programming language must be supplied by external configuration files and deployment descriptors.

  5. The Web service API is cumbersome to package and deploy.

    The application container expects executable code and its associated deployment descriptors to be packaged in a specific way. The expectations can vary from container to container, depending on the standards that have been defined by the programming language and the level of standards support by the container. This variability and added complexity can create the potential for a cumbersome package and deploy process.

  6. Code-first is not an option when the contract isn't maintained by the provider.

    There are some cases where the provider is required to implement a Web service API that is defined by an externally-maintained contract. This requirement precludes the code-first development model as the developer must start with the contract.

3.5 Advantages of Contract-First Development

The advantages of the contract-first development model are in many ways the complement to the disadvantages of the code-first development model: 

  1. Interoperability is generally enhanced.

    When the Web service API contract is created and maintained directly by the developer, interoperability is more readily secured through accuracy and flexibility. Accuracy is promoted because the developer is obligated to write the implementation of the interface that the contract defines. Flexibility is promoted because the developer isn't limited by the capabilities of the application container. Furthermore, the contract isn't rigid; it can be changed and negotiated between the provider and the consumers of the API. This process of negotiation ensures that the contract is clear and acceptable to both the provider and the consumer. The developer can also ensure that the contract conforms to the desired level of compatibility with common interoperability standards.

  2. User-level documentation can be maintained in tandem with the contract.

    Since the contract isn't generated by an engine, the developer has the flexibility to define both the syntax and the semantics of the Web service API in a common logical location. This promotes the practice that the user-level documentation and the formal WSD are to be maintained conjointly, reducing the possibility that they are out of sync.

  3. The contract can present a broader, more complete view of the Web service API.

    The developer of the contract can arrange the definitions of the Web services in a way that related services are grouped together and share common data structures. While the semantics of the API would still need to be described by user-level documentation, placing related services together in the contract establishes a context that enhances contract readability.

  4. It's the only model available when required to implement a contract that isn't maintained by the developer. 

3.6. Disadvantages of Contract-First Development

Proponents of the contract-first development model are often slow to recognize the significant cost of supporting it: 

  1. The language of the contract is difficult to learn and understand, and it requires significant expertise.

    The specifications that support the definition of a Web service API are very complex. Developers of a contract-first model are required to understand the structure of the contract, the abstract concepts of Web service development, and the subtleties of how the contract is implemented by both the provider and the consumer of the API. Furthermore, the tools that support contract development are usually immature and often foreign to the developer.

  2. The contract is disconnected from the implementation.

    The disconnect makes the API difficult to maintain because the implementation has to be linked to and verified against the API. It also allows for the possibility of the implementation being out-of-sync with the API. This problem is normally reduced through the use of code generation tools to generate a set of source code interfaces that the implementation can be compiled against. However, even with the leverage of code generation tools, the process to make a change in the contract is burdensome.

  3. The language of the contract is less strict than most programming languages, so constraints have to be applied to the contract to ensure that the API can be supported.

  4. The Web service API is cumbersome to package and deploy.

    This is a disadvantage shared with the code-first development model, but because the contract-first development model consists of more steps, the problem is generally more pronounced with contract-first development.

3.7. The Development Decision: Code-First or Contract-First?

The difficulty of the choice between Web service development models is perhaps indicative of the reason that Web services have been slow to reach their full potential. The code-first development model provides an easy way to create and maintain a Web service API, but at the cost of lower interoperability. On the other hand, the contract-first development model provides a boost to interoperability, but it is more costly to maintain, in terms of expertise and development time.

Historically, the Web service API provider has had to make a decision between these two development models by weighing the need to be interoperable (given its potential consumers) against the cost of publishing and maintaining the Web service API. Generally, providers that are most concerned with interoperability have chosen to incur the costs of a contract-first development model. Providers who lack the time, resources, or expertise (or those who are less concerned about interoperability) have chosen a code-first development model.

4. Compiled Contract

The compiled contract development model introduces an entirely new approach to Web service API development. It is, in a way, an extension of the code-first development model in that the API is developed and maintained in source code, allowing developers to define the API in a language with which they are familiar.

The compiled contract model introduces a new concept to the code-first development model. During the compile step, the source code is not only compiled to produce the executable agent code, but also to produce the Web service API contract. This means that the source code is processed and validated in terms of the syntax and semantics of both the the programming language and Web service API contract. The compile step fails if the source code fails to compile to either the executable code or to the Web service API contract.

The tool used to compile the contract is referred to as the contract compiler. The contract compiler must be aware of how the code will be published as a Web service API when deployed in an application container so as to produce an accurate contract. The contract compiler fails if unable to produce a contract that is unambiguous and interoperable according to widely-established standards for interoperability.15 The contract compiler should also produce any human-oriented documentation that specifies the semantics of the Web service API in addition to the formal WSD so as to create a complete contract.

At this point in the development cycle, the entire contract is packaged along with the executable code and necessary deployment descriptors to create the agent artifact. This step could also be facilitated by the contract compiler, that could produce the deployment descriptors, the agent artifact, or both.

When deployed, the application container publishes the executable code as specified by the deployment descriptors as Web service API agent, but it does no work to generate the Web service API contract, instead publishing the contract that was generated at compile-time. 

The compiled-contract development model is illustrated in Figure 4-1. 

Compiled contract development

4.1. Advantages of Compiled Contract Development

The advantages to the compiled contract development model include advantages from both the code-first and contract-first development models. The compiled contract model also solves some problems that neither of the other development models address:

  1. The entry barrier to Web service development is low and the learning curve is gentle.

    Like the code-first development model, this is because development is done in a common programming language.

  2. Interoperability is enforced by the process.

    If there are any ambiguities in the Web service API provided by the agent implementation, the contract fails to compile. The rules governing interoperability are integrated into the contract compiler. This removes the burden of interoperability expertise from the developers of the agent and consolidates it with the developers of the contract compiler who specialize in understanding interoperability. Furthermore, errors and ambiguities in the contract are exposed earlier in the development process—at compile-time—rather than at runtime, after the application is deployed.

  3. The Web service API, as defined by the contract, is fixed to its implementation.

    This is an advantage shared with the code-first development model, but it is the result of a compile-time assembly, rather than a runtime generation by the application container.

  4. User-level documentation can be maintained in tandem with the contract.

    Because the contract is compiled from source code, documentation of the Web service API can be extracted from the code comments. The ability to do this depends on the capabilities of the contract compiler.

  5. The contract can present a broader, more complete view of the Web service API.

    Programming languages often specify a way of packaging related structures. This mechanism can be leveraged to preserve the same view of related services.

  6. The Web service API can be created, updated, and refactored using standard tools and Integrated Development Environments (IDEs). 

  7. The packaging and deployment of the Web service API can be facilitated by the contract compiler.

    Along with compiling the contract from source code, the contract compiler can facilitate deployment of the Web service API application by also generating the necessary deployment descriptors and packaging the agent artifact. The ability to do this depends on the capabilities of the contract compiler.

4.2. Disadvantages of Compiled Contract Development

Despite its numerous advantages, there are two disadvantages that may preclude using the compiled contract development model: 

  1. There must be a contract compiler available for the programming language.

    A contract compiler is a complex tool. The viability of developing a contract compiler varies from platform to platform, depending on the capabilities and features of the programming language. High-level, compiled, object-oriented programming languages tend to be the most practicable candidates because these languages can most reasonably and deterministically be mapped to the language of the Web service API contract. The most mature programming languages even provide specifications that define how the language can be mapped to a contract.

  2. Like code-first development, compiled contract is not a viable option when the contract isn't maintained by the developer. 

5. Conclusion

The compiled contract model should be the preferred approach to Web service development because of the significant advantages it has over code-first and contract-first development. Assuming there exists a contract compiler for the selected programming language, only a requirement to implement an externally-maintained contract should preclude using the compiled contract model.

The compiled contract model allows maximum flexibility to the Web service API developer through code-first development, while concurrently enforcing the high level of interoperability sought for when applying contract-first development. 

Appendix A: Notes and References

1. The Web Services Interoperability Organization (WS-I) provides a document that defines a set of Web service specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability. The document is referred to as the WS-I Basic Profile. For the latest revision, see http://members.ws-i.org/dman/Docs.phx?Working+Groups/WSBasic+Profile/Profile/BP1.2/BasicProfile-1.2-WGD.html.

2. World Wide Web Consortium, Web Services Architecture, “What is a Web service?” (See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#whatis).

3. World Wide Web Consortium, Web Services Architecture, “Requesters and Providers” (See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#reqpro).

4. See Note 1.

5. World Wide Web Consortium, Web Services Architecture, “Agents and Services” (See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#id2260073).

6. World Wide Web Consortium, Web Services Architecture, “Agents and Services” (See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#id2260073).

7. See http://java.sun.com.

8. See http://msdn2.microsoft.com/en-us/vcsharp/aa336809.aspx.

9. World Wide Web Consortium, Web Services Architecture, “Service Description” (See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#id2263315).

10. See http://www.w3.org/TR/soap/.

11. See http://www.w3.org/Protocols/.

12. See http://www.ietf.org/rfc/rfc2045.txt.

13. World Wide Web Consortium, Web Services Architecture, “Semantics” (See http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#id2263364).

14. For a more complete analysis of this problem, see http://tssblog.techtarget.com/index.php/uncategorized/a-rant-of-sorts-on-multiple-net-web-references/

15. See Note 1.