SOA Versioning Best PracticesAl Ghoniem

Introduction This paper is highlighting best practices recommended for WSDL, Services versioning in SOA environment.

Changes that triggers version numbers increments

ChangeBreaking Compatibility MajorMinorPoint

Removing an operationXX

Renaming an operationXX

Changing the parameters (in data type or order) of an operationXX

Changing the structure of a complex data typeXX

Changing the MEP of an existing WSDL operation definitionXX

Adding a fault message to an existing WSDL operation definitionXX

Adding a new required XML Schema element or attribute declaration to a message definitionXX

Increasing the constraint granularity of an XML Schema element or attribute declaration of a message definitionXX

Renaming an optional or required XML Schema element or attribute in a message definitionXX

Removing an optional or required XML Schema element or attribute or wildcard from a message definitionXX

Adding a new required WS-Policy assertion or expression.XX

Reducing the constraint granularity of an XML Schema element or attribute declaration of a message definition.X

Adding a new optional XML Schema element or attribute declaration to a message definition.X

Adding a new WSDL operation definition and associated message definitionsX (Some Rescores. says this is a minor Releases)

Adding a new WSDL port type definition and associated operation definitionsX

Adding new WSDL binding and service definitionsX

Adding a new optional XML Schema element or attribute declaration to a messageDefinitionX

Adding a new XML Schema wildcard to a message definition typeX

Adding a new optional WS-Policy assertionX

Bug fixX

Performance enhancementX

WSDL Versioning best practices

1- Add major-version information to the WSDL definitions target namespace and file name.The exception to the preceding rule is when the first version of a WSDL definition is released. In this case, no version number is added to the namespace.

Rationale: By encoding only the major release number in the namespace, successive minor releases share the same namespace and so are compatible.

Examples:

Notes :Consider using prefix v as follows:definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:cmm="http://www.ventyx.com/ims/cmm/oagis/9.5.1" xmlns:oa="http://www.openapplications.org/oagis/9/" xmlns:tns="http://www.ventyx.com/ims/ws/oagis/9.5.1/v2" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" name="Shipment" targetNamespace="http://www.ventyx.com/ims/ws/oagis/9.5.1/v2">

2- Minor and major contract version numbers will be expressed using a documentation element that follows the opening definitions element.The version numbers will be displayed after the word Version

Rationale: WSDL does not have standard version element.Examples:

2.0For Multiple versions :Version 1.0, 2.0

3- Encode major and minor version in the target namespace of the WSDL section.

Rationale: An explicit system of record for the incremental changes to the interface.Examples:

4- Embed major-minor version in the interface (portType) name.

Rationale: The interface name is mapped to the service endpoint interface in a destination language; by making the interface version explicit we allow the same code-base to implement different versions of the same interface.Examples:

5- Embed major-minor version in the service name.

Rationale: Using the same name for the service as that used for the interface.Examples:

6- Embed major-minor version in the Policy.

Rationale: Change in Policy will trigger an increment in Major-Minor numbers.Examples:

Question: Major change numbering only?

Do Not(s):

1- Do not use date (year/month) for WSDL versioning :This approach is used by XSD designers, where the date is embedded in the schema target namespace to indicate major release information and also give historical reference. Some WSDL designers have in the past used this approach in WSDL contracts; while it does facilitate major versioning it introduces a new lexical namespace with every contract and so renders the new contract incompatible with previous versions.

2- Avoid embedding versioning information in message names: The reason for this is that WSDL code generators that adhere to the wrapped-doc-literal convention require that the name of the message be the same as the name of the operation, so that they can detect the presence of the wrapped convention and generated appropriate method signatures.

Management of concurrent instances of a service with different versionsApproach ProsCons

XML Extensions : Using xs:any and xs:anyAttribute Compatibility by ignoring unknown elements.If not well designed, in valid XML can be passed.

Service adapters :Intercepting the message apply XSLT if the message is not computable then send it through o the serviceClients using old version will use the new version seamlessly.Performance overhead.Technical overhead.Will not encourage w=the client to upgrade to he new version of the service.

Namespace Versioning: Explained earlier in WSDL versioning..NET can resolve XML namespaces using XMLNameSpaceManager Performance overhead

WS-Addressing custom Tags:Useful to keep track and relay Implementation and Interface changes.Can include reach information about implantation or Interfaces changes.Using custom non-standard tag, that will not be understood by all platforms.

Will require intercepting the message which will add performance overhead.

Service Brokers and UDDI :Recommended for more than 30 services. Has reach features for versioning and the discovery of services, especially when many services exists.Administration overhead.