Specifying versions for web services

This section describes how to specify versions for an implementation and how BMC specifies interface versions.

To specify versions for the interfaces

To specify interface versions, you can use the following methods:

• Date and timestamp for the web services description language (WSDL)
• Version and revision information stored in the Universal Description, Discovery and Integration (UDDI)

Usually including a date or timestamp ensures that interface versions are unique, which follows the guidelines given by W3C:

http://www.w3.org/TR/REC\-xml\-names/

For example, for the first version of a web service interface, the following schema tag in the WDSL indicates the version with the 2009/02/15 date:

<schema targetNamespace="http://bmc.com/2009/02/15/myService.xsd" xmlns="http://www.w3.org/2000/10/XMLSchema">

When WSDL changed, the new version of the service is specified with the 2010/10/23/ date:

<schema targetNamespace="http://example.com/2010/10/23/myService.xsd" xmlns="http://www.w3.org/2000/10/XMLSchema">

BMC also stores interface version information in the UDDI, following the <version>. <majorRevision>. <minorRevision> model used for other types of software. To access this additional version information in the UDDI, use the publish and find APIs which support versioning:

• Publication of the service interface version
• Querying the service interface version

Version IDs or numbers comply with the following principles:

• A minor version should be backward compatible with other minor versions associated with a major version. For example, interface version 1.1 should be fully backwards compatible with interface version 1.0. Minor versions should never break backward compatibility. A minor release can include new operations and bug fixes that do not change the signatures of existing operations.
  A minor update can use the same targetNamespace. For example, a 2.5.1 update can use the same targetNamespace as 2.5.0.
• A major version might break backwards compatibility with clients created for other major versions. For example, interface version 2.0 might not be backward compatible with version 1.0.
  Also, the targetNamespace should always map to a major version, and a new major version must have a new targetNamespace.

Examples of changes for a major version include deleting methods or functions, changing names, and changes to parameters.

BMC CMDB does not automatically enforce or check these principles for web services, but you should follow these principles to ensure that clients can work with minor versions without having to be updated.

For more information about creating clients that can work with different versions of the interface, see Best practices for backward compatibility of web services.

To specify versions for the implementation

You can create versions for the logic that implements a service, even though you have not changed the service's interface or web services description language (WSDL).

In most cases, client applications dependent on the service should not have to be re-written when a new version of a service's implementation is introduced.

You can specify the implementation version with the serviceVersion parameter in the Web Registry API.

The WSRegistryAPI comes with a test driver TestUDDIRegistry in the com.bmc.webservices.uddiapi.test package. You can use this test driver to publish and find service endpoints with implementation versions. For example, to publish a service with an implementation version, you could use the following command syntax:

publish  <BusinessName> <ApplicationName> <ServiceName> <ServiceVersion ServiceInterfaceVersion>
 " <ServiceDescription>
"  <AccessPointUrl> <WSDLUrl> <CriteriaList>

In the following example, the CMDB_Service is assigned an implementation version of 1.1, but the interface version remains 1.0.

publish BMC_INC CMDB_APP CMDB_Service 1.1 1.0 "My CMDB Service" http://myhost:8080/cmdbws/server/cmdbws http://myhost:8080/cmdbws/server/cmdbws?wsdl= (bmc.com:categorization:geography,Sunnyvale) (bmc.com:categorization:organization,ITSM)

To find a service with a specific implementation version, use the follow syntax:

findsvc  _BusinessName_ _ApplicationName_ <ServiceName> <ServiceVersion ServiceInterfaceVersion ApproximateMatch> <CriteriaList>

The following example is a search for CMDB_Service using a wildcard for the implementation version and would return all CMDB_Service instances with an implementation version range of 1.0 through 1.9 and with an interface version of 1.0.

findsvc BMC CMDB_APP CMDB_Service 1.* 1.0 Y (bmc.com:categorization:geography,S.) (bmc.com:categorization:organization,.*)