SOA Development - Explicit or Implicit Versioning

When defining service versioning policies, one thing that must be considered is whether or not consumers are required to explicitly specify the version of a service that they will use or not. For example, when using a service that is accessed via HTTP, the service invocation must specify a URL.

This applies whether the service requires a SOAP envelope or if the service is using a resource model provided via REST URLs. For Advasco, a URL used internally for a service will look like this:

http://services.advasco.com/BooksRecords/Customer

In this example, there is no explicit version number associated with the URL. All we can infer is that the request is directed at the host named services.advasco.com for a service at the path of /BooksRecords/Customer. In the case of Advasco, a URL naming standard enforced at a design checkpoint requires that the first portion of the path expresses the domain of the service, in this example, BooksRecords, while the second portion of the path expresses the service desired within the domain, in this example, Customer. If there were multiple versions of this service available, the version required for the request must be determined according to the identity associated with the request. Identity is normally passed through transport headers associated with the HTTP transport, or as part of the message itself. In the case of SOAP-based services, the message can contain both header elements and the message body. The WS-Security specification defines a standard location in the SOAP header for security credentials. For example, a SOAP request for a Customer Information Service may look like this:

In this example, the namespace element of the message is http://schemas. advasco.com/books-records/customer/nov-2008/. At the end of the URI for the namespace, there is a month and date that can tell the recipient of the message that the schema used in this message corresponds to the November 2008 version of the Customer schema. It is entirely possible that even the namespace of the message may not contain an explicit version identifier; however, the version of the message can be determined by looking for the inclusion, or exclusion, of specific message elements.

Another example of a SOAP request could be the following:

In this example, neither the URL for the request nor the XML namespace gives any indication of the version of the service desired. The only thing this message has is the identity of the consumer. This example uses the WS-Security UsernameToken profile and specifies a username of jdoe. Through the use of a service contract, this consumer can now be associated with a particular version of the service via policies. An intermediary can receive the message, check the policies associated with the contract for this consumer, and then either route to the appropriate endpoint or apply transformations to preserve backward compatibility.