By following this advice, you will find that a number of simple interoperability problems will not surface. Surprisingly, this is the only nonintuitive thing to look for. From the list of participating options, choose one that supports the language and platform you prefer to work with. If you don't find a compatible toolkit, either pick a new language or prepare to develop one. While developing the new toolkit, make sure you join in with a community that does testing across Web service stacks. SOAPBuilders does this today. Other groups, such as WS-I, will have more advanced forms of interop testing in the near future.

While not a requirement, you will find that interoperability will be at its best if the particular SOAP toolkit has some form of representation in WS-I.org. The representation indicates that the organization behind the Web service implementation wants the interoperability to go deeper than things like "can the toolkit read and send a complex type." WS-I.org will look at the complete scenario: discovery, proxy generation, message exchange, etc., and make sure the toolkit can do it all.

Choosing a Data Representation
A good number of interoperability problems happen due to developer choices, not SOAP toolkits. Here is an example of a developer choice that results in a WSDL-type definition that is hard to use:

<xsd:complexType>
<xsd:sequence>
<xsd:element ref="xsd:schema" />
<xsd:any />
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="Map">
<xsd:sequence>
<xsd:element name="item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="key" type="xsd:anyType" />
<xsd:element name="value" type="xsd:anyType" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>

In case you don't recognize the above snippets, the first one is the result of telling ASP.NET to return a System.Data.DataSet. The second one is an Apache SOAP serialization representation of java.lang.Hashtable. Instead of returning one of these non-interoperable types, you could choose to return something that is more likely to interop. For example, when returning tabular data, it is fairly unlikely that the number and names of the elements will vary based on inputs to the Web method. Most of the time, the tabular data will contain the same types. Instead of returning a generic type, the WSDL and corresponding source code could be modified to return something that other toolkits can more easily import and use. How could something like the ASP.NET example be improved?

Let's assume that the DataSet is populated with product data. I could define the array of data with the schema shown in Listing 1 .

Now, any consumers of the data know exactly what the response SOAP will look like. Instead of needing to process the returned message with XML, the client program could use native classes. Most SOAP toolkits are capable of translating between the XML and object representation of data. Well-defined WSDL allows the toolkit to generate these objects with no to little developer intervention.

You can get similar problems when just stuffing XML inside of the SOAP Header or Body. Unless the XML is really generic (and it rarely is), take the time to define what the WSDL will look like. Often, this choice is made when the developer knows things will be changing and they don't want to update the WSDL in order to change the code providing the Web service. Any time you change the way a Web service behaves, you will probably break a downstream client somewhere. Take a little extra time and define what the returned XML will look like. When you update the back-end Web service, plan some time in the schedule to write a new version of the WSDL.

Often, when using SOAP, the developer knows that they want to handle messages as raw XML. That's fine. Still, the returned XML will typically follow a set schema. Define that schema in your WSDL, even if you don't rely on object serialization/deserialization. Just don't take away the ability to generate smart clients from any end users. By providing schema, you make the end user's life much easier.

This last bit of advice invariably brings up the question: what should I do with two WSDL files? The issue: most people want to avoid having too many side-by-side versions of a Web service up and running. One solution is to have a regular release cycle and make sure that users of the Web service understand that the service will only be available for a fixed amount of time. For example, put documentation in the WSDL that states when the service endpoint will end service. If the Web service requires a preexisting arrangement (such as a signed contract) before a user begins accessing the service, put language in the contract explaining how frequently the Web service will be updated and how long any given version of the Web service will be available. This still means that you will wind up running multiple versions of the same Web service at the same time. Thankfully, it gives you a way of limiting how long versions need to be available.

Finally, since you are using WSDL and schema anyhow, you might as well code the Web service to emit a document/literal representation of the data instead of rpc/encoded. There are situations where rpc/ encoded still shines. Namely, if you are serializing a complex object graph and the relationships need to be maintained, use rpc/encoded. Otherwise, stick with document/literal representations of data.

Summary
To achieve Web service interoperability, the tools vendors have banded together and created two organizations: SOAP Builders and WS-I.org. SOAPBuilders is an informal group that works at getting fundamental issues around interoperability resolved. At the other end of the spectrum, WS-I.org provides a more formal structure that rigidly defines what it means to be interoperable and the set of protocols that are being worked on. WS-I.org provides architectural guidance, testing tools, and sample applications that aid in the understanding and adoption of Web services. We need both organizations to solve the issues around interoperability and Web service adoption and general understanding. Why? Some implementations of SOAP stacks, such as SOAP::Lite (Perl) and pocketSOAP (COM/PocketPC), may never have corporate backing. Implementations like these are valuable and need some forum in which to verify interoperability with the Web service stacks offered by corporate entities.

As a developer of Web services, you should take advantage of the work the interoperability groups are doing by only using SOAP toolkits that are actively involved in SOAPBuilders. It makes your life easier because you are using a toolkit that is being tested against other toolkits. Issues are discovered and fixed through this testing.

When developing a Web service, avoid declaring the return of generic XML in WSDL files. Instead, declare exactly what you are returning via schema and return that instead. Is generic XML useful in interop scenarios? Yes. But most scenarios do not require or benefit from the ability to send and read weakly expressed XML. Unless you really need that ability, express the format of the returned message in XSD contained or referenced from the WSDL description of the Web service.

About The Author
Scott Seely is a member of the MSDN Architectural Samples team. Besides his work there, Scott is the author of SOAP: Cross Platform Web Service Development Using XML (Prentice Hall PTR) and the lead author for Creating and Consuming Web Services in Visual Basic (Addison-Wesley). sseely@microsoft.com

Building Interoperable Web Services, by Scott Seely
WSJ Vol 02 Issue 09 - pg.33

	


Listing 1

<xsd:complexType name="ArrayOfProduct">
    <xsd:sequence>
        <xsd:element minOccurs="0" 
            maxOccurs="unbounded" 
            name="Product" nillable="true" 
            type="s0:Product" />
    </xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Product">
    <xsd:sequence>
        <xsd:element minOccurs="0" maxOccurs="1" 
            name="QuantityPerUnit" type="xsd:string" />
        <xsd:element minOccurs="1" maxOccurs="1" 
            name="UnitPrice" type="xsd:decimal" />
        <xsd:element minOccurs="0" maxOccurs="1" 
            name="CategoryName" type="xsd:string" />
        <xsd:element minOccurs="0" maxOccurs="1" 
            name="SupplierName" type="xsd:string" />
        <xsd:element minOccurs="0" maxOccurs="1" 
            name="Name" type="xsd:string" />
        <xsd:element minOccurs="1" maxOccurs="1" 
            name="ID" type="xsd:long" />
    </xsd:sequence>
</xsd:complexType>