Web Service Versioning

Service Version - This article is work in progress

Service Version - This article is work in progress

There is no one versioning approach that is right for everyone. Because versioning represents a governance-related phase in the overall lifecycle of a service, it is a practice that is subject to the conventions, preferences, and requirements that are distinct to any enterprise.

Three known strategies:

• Strict – Any compatible or incompatible changes result in a new version of the service contract. This approach does not support backwards or forwards compatibility.

• Flexible – Any incompatible change results in a new version of the service contract and the contract is designed to support backwards compatibility but not forwards compatibility.

• Loose – Any incompatible change results in a new version of the service contract and the contract is designed to support backwards compatibility and forwards compatibility

Scenarios

This paper(see link below) groups service versioning options into two categories:

• Message Versioning—Focuses on versioning the schemas used to describe messages processed by the service.
• Contract Versioning—Focuses on versioning the WSDL and contract information used to describe the service.

Message versioning


Message versioning implies XML Schema related versioning. There are several common techniques for XML versioning and extensibility techniques available:

• Namespaces
• Extension Elements
• Custom version attributes

Namespaces and Extension Elements

There are several options for versioning or extending a schema using XML Namespaces:

1. Use a new XML Namespace for major version releases
2. Keep XML Namespace values constant and add an XML Schema version attribute
3. Keep XML Namespace values constant and add a special element for grouping custom extensions

Design Principle #1:

Use targetNamespace to communicate major version releases

Rationale:

Major version releases are typically breaking changes.
Ease of implementation and support.

Judicious use of <xsd:any>

Adding <xsd:any> enable you to enter anything in that. Its good in that you could add any extra tag when required, but drawback of this is that it would not be validated with XML schema, so it could be used in short term quick changes scenario.

Design Principle #2:

Judicious use of unambiguous wildcards can help minimize service versioning.

Rationale:

Extensible schemas adapt to meet changing user or service needs.

Extensible schemas minimize versioning due to schema enhancements.

The W3C Web Services Description Working Group is developing a set of
Adjuncts for WSDL 2.0. The Adjuncts will provide a set of predefined
extensions to WSDL 2.0 and will appear in Part 2 of the specification.
WSDL 2.0's predefined extensions were designed for message exchange
patterns, operation styles, and bindings. The extensions define a SOAP
Header Block that could be used to extend schemas by adding the new
data structures within the WSDL........ more on this later on

Contract Versioning

Contract Versioning implies WSDL versioning.

• Adding a new operation—Adding a new
  operation to a service does not break existing consumers since they
  will be unaware of the new operation's existence. Newer consumers can
  then take advantage of these new operations without breaking existing
  consumers.
• Adding new data structures and data types—New
  data structures and data types can be added as long as the old ones are
  preserved. New, optional structures and data types added to the end of
  messages sent to services will not break existing consumers since they
  will be unaware of the new data structures. Services can also expand
  the range of possible data values or types they can accept without
  impacting existing consumers (assuming a doc-literal encoding style is
  utilized).
• Adding a new interface for an existing operation—Once
  again, existing consumers will be unaware of the new interface and will
  be unaffected by it. Newer consumers will have a choice of interfaces
  to utilize.
• Remember the First Tenet—The
  first tenet of Service Orientation tells us that boundaries are
  explicit. A boundary represents the border between a service's public
  interface and its internal, private implementation. Service internals
  can be modified, evolved, or totally rewritten as long as the contract
  for that service remains unchanged. When service implementation details
  leak into the service boundary this freedom is lost and the contract
  becomes much more fragile.
• Type restriction in response messages—Response
  messages cannot, for the most part, be modified without breaking
  existing consumers. Services may restrict the range of possible types
  sent as a response without breaking the contract, depending on how a
  given consumer has been developed. Consumers will most likely still
  expect a given range of response values without realizing that the
  range of possible responses has just been reduced in scope.
• Use <wsa:Action>—ASMX
  uses the soapAction header to perform message dispatching by default.
  This enables service operation names to change without impacting
  consumers because the soapAction remains constant. soapAction is only
  valid over HTTP because the WSDL specification restricts its usage to
  HTTP. Luckily, WS-Addressing's <wsa:Action> element can be used to communicate intent across any protocol (even HTTP).
• Use a Service Broker—A
  service broker serves as a front-end to the targeted service,
  redirecting the request to the appropriate version of the service,
  based upon the content of the request itself. Service brokers are
  available as commercial products or can be specialized services
  designed to serve as façades for existing systems.

Design Principle #4:

When adding new data structures, make them optional and add them to the end of service request messages.

Rationale:

Existing consumers remain unaware of the new data structures.

Design Principle #5:

Changing service response messages (other than type
restrictions) are breaking changes and will require a new version of
the service.

Rationale:

Existing consumers cannot serialize unexpected data structures.

Conclusion

Six design principles were identified to summarize best practices
for service versioning. This is not a static list and will likely grow
as the Web services specifications continue to evolve:

1. Use targetNamespace to communicate major version releases.
2. Judicious use of unambiguous wildcards can minimize service versioning.
3. Extensions must not use the targetNamespace value.
4. When adding new data structures, make them optional and add them to the end of service request messages.
5. Changing
   service response messages (other than type restrictions) are breaking
   changes that will require a new version of the service.
6. Adopt a one-to-one relationship between interface versions and UDDI tModels.

http://msdn.microsoft.com/en-us/library/ms954726.aspx