Principles and Motivations
| Retired Content |
|---|
The Web Service Software Factory is now maintained by the community and can be found on the Service Factory site. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. Retired: November 2011 |
This section represents the principles and motivations that provide the backdrop for the strategies in the next section. In addition to the concepts and scenarios in the previous sections, this section will help you understand the reasoning that went into the strategies.
Favor Evolution over Creation
Changes result in either a service evolving or a new service being created. Minor versions represent an evolution, and major versions effectively represent new services because they explicitly prevent any form of compatibility. This level of distinction is important for clearly communicating expectations; it can also influence decision making for specific changes.
Creating new services is expensive because of the added responsibilities in the following list:
- Each new endpoint address must be managed, monitored, secured, and in many cases, reported upon.
- Each new endpoint address must be documented and clearly communicated so the consumers do not run the risk of being confused by multiple (seemingly similar) services.
- Each new service requires the deployment of consumers of that service.
There is little to no evidence that suggests that creating new services minimizes complexity for either the team building the service or the team building the consumers.
Unfortunately, there are times when a graceful evolution is not an option. The most common scenario that mandates the service undergo a major version change is a change in a business requirement. These changes can undermine any technical strategy you put in place. For example, adding a new field to a request message usually does not dictate a major change from a technical standpoint. However, if a change in a federal policy or specification your business must comply with enacts a change that you must now collect information the consumers of your service are not currently sending, this will results in a new service that requires the deployment of new consumers.
Use Artifacts Appropriately
In order for a service to be used, the team building the service provides various documentation artifacts to its consumers. Examples are the service description (WSDL), policy files, registry/metadata information, and various documents that describe the API and service interaction patterns. Some of these artifacts will be read by humans and others will be acted upon by tools such as Visual Studio. As part of the communication to the service's consumers, it is important to include how these artifacts should be used and what the expectations are surrounding their use.
The WSDL document potentially contains a lot of information about the service and is typically only read by tools instead of humans. Historically, the WSDL has been used for multiple purposes:
- Code generation. This code can generate service-related code, but most of the time it is used to create proxy code for the consuming application.
- Communicate service requirements. Depending on the actual requirements being communicated, this may be an appropriate use of the WSDL. For example, the shape of the messages, the names of the operations, and binding information is all appropriate because it can be adequately and consistently interpreted by tools.
- Enforce service requirements. This is an inappropriate use because it cannot adequately or consistently be accomplished by tools. WSDL does include XML Schema documents to define the types that comprise the messages, but very few tools support translating the validation rules in a meaningful way. Also, when it comes to the broader topic of message validation, XML Schema validation is not as robust as other approaches.
The WSDL document describes the shape of the service instead of the requirements of the service. Because WSDL is only effective as a code generation artifact, it should only be used as such. Likewise, it should only be used to generate specific code (such as consumer's proxy, a stub of the service, and associated message classes) and the expectations for this code should also be communicated. Other, external documents are more appropriate to communicate the requirements of a service.