This chapter is from the book
This chapter is from the book
This chapter is from the book
Version Identification
By David Orchard, Chris Riley
How can consumers be made aware of service contract version information?
Table 16.2. Profile summary for the Version Identification pattern.
|
Problem |
When an already-published service contract is changed, unaware consumers will miss the opportunity to leverage the change or may be negatively impacted by the change. |
|
Solution |
Versioning information pertaining to compatible and incompatible changes can be expressed as part of the service contract, both for communication and enforcement purposes. |
|
Application |
With Web service contracts, version numbers can be incorporated into namespace values and as annotations. |
|
Impacts |
This pattern may require that version information be expressed with a proprietary vocabulary that needs to be understood by consumer designers in advance. |
|
Principles |
Standardized Service Contract |
|
Architecture |
Service |
Problem
Whether a contract is subject to compatible or incompatible changes, any modification to its published content will typically warrant a new contract version. Without a means of associating contract versions with changes, the compatibility between a service and its current and new consumers is constantly at risk, and the service also becomes less discoverable to consumer designers (Figure 16.4).
)
Figure 16.4 As a service contract is required to change, a service consumer is left in the dark as to whether it is still compatible.
Furthermore, the service itself also becomes more burdensome to govern and evolve.
Solution
The service contract can be designed to express version identifiers that allow the consumer to confidently determine whether it is compatible with the service. The use of version identifiers further supports Concurrent Contracts (421) for versioning purposes, thereby allowing a consumer to choose the correct contract based on its expressed version, as shown in Figure 16.5.
)
Figure 16.5 Because the service contracts express versioning information, Consumer A can proceed to invoke version 3 of the service contract because it was designed to be compatible with that specific version.
Application
Versions are typically identified using numeric values that are incorporated into the service contract either as human-readable annotations or as actual extensions of the technical contract content. The most common version number format is a decimal where the first digit represents the major version number, and digits following the decimal point represent minor version numbers.
What the version numbers actually mean depends on the conventions established by an overarching versioning strategy. Two common approaches are described here:
- Amount of Work– Major and minor version numbers are used to indicate the amount of effort that went into each change. An increment of a major version number represents a significant amount of work, whereas increases in the minor version numbers represent minor upgrades.
- Compatibility Guarantee– Major and minor version numbers are used to express compatibility. The most common system is based on the rule that an increase in a major version number will result in a contract that is not backwards-compatible, whereas increases in minor version numbers are backwards-compatible. As a result, minor version increments are not expected to affect existing consumers.
Note that these two identification systems can be combined so that version number increases continue to indicate compatible or incompatible changes, while also representing the amount of work that went into the changes.
With Web service contracts specifically, a common means of ensuring that existing consumers cannot accidentally bind to contracts that have been subject to non-backwards-compatible changes is to incorporate the version numbers into new namespace values that are issued with each new major version increase.
Impacts
Version identification systems and conventions are typically specific to a given service inventory and usually part of a standardized versioning strategy, as per Canonical Versioning (286). As a result, they are not standardized on an industry level and therefore, when expressed as part of the technical contract, impose the constant requirement that service consumers be designed to understand the meaning of version identifiers and programmatically consume them, as required.
When services are exposed to new or external consumers, these same requirements apply, but the necessary enforcement of standards may be more difficult to achieve.
Relationships
This pattern is commonly applied together with (or as a result of) the application of Canonical Versioning (286) and is further an essential part of carrying out Compatible Change (465).
)
Figure 16.6 Version Identification relates primarily to other contract versioning patterns.