The March Toward Interoperability

As you can see, the house that SOAP built isn’t quite the penthouse overlooking Central Park West just yet, but enough thought and effort is going into it that it should be quite something when it’s finished. That is, if something else doesn’t supercede it first.

In the meantime, a lot of developers and a lot of toolkits are trying to live under the one roof. True interoperability is (or at least should be) the focus of all Web service toolkits today, but most of them just don’t work well together yet. A great deal of tweaking is inevitably required to get a service working against them all. Having standards helps a lot, but toolkit developers continue to find different ways to interpret them and, of course, they’re always trying to include unique selling points in their kits that don’t actually make the services created with those toolkits any more compatible with other kits or with services created elsewhere. .NET uniquely defines a documentation request type— for example, a GET request with no query string. Will Web service toolkits ever implement a single set of common functionality?

The efforts to improve Web service interoperability across the board include

• The SOAPBuilders community (http://www.soapbuilders.org), a project to get every platform and toolkit working with the others while adhering to ratified standards. It’s worth noting that after three years, they’re still trying to get SOAP encoding to reconcile across the board. More on this later.

• The Web Services Interoperability Organization (WS-I), an independent body that judges and guides toolkit vendors in their implementations of the standards. It has issued a document that outlines criteria for toolkits, along the lines of the WSA draft from the W3C. This Basic Profile document was released as a working draft in October 2002. You can find it at http://www.ws- i.org/Profiles/Basic/2002-10/BasicProfile-1.0-WGD.htm.

We’re making an issue of this lack of compatibility between platforms because it is truly widespread—across every layer of the wire and description stacks. Here are some of the affected areas:

• Transport layer The SOAPAction HTTP header is mandatory, and its value must be surrounded by quotes, according to SOAP 1.1. However, some toolkits can’t actually create the header or leave off the quotes.

• Packaging layer Some toolkits don’t check for or even register the SOAP mustUnderstand header.

• Interface definition layer Different toolkits support different versions and different pieces of the Schema spec. The .NET serializer, for example, has a few problems with substitution groups.

• Implementation description Only a few toolkits support both doc/literal and RPC/encoded-style messages, and those do not all do it in the same way. Also, different toolkits generate different WSDL documents given the same service, and these documents must be altered before they are usable by a different toolkit. For example, wsdl.exe includes entries for HTTP-GET requests in .NET WSDL documents, which mean nothing to other toolkits.

• Extended WSA Each vendor’s toolkit supports only its own solutions to its own problems.

Solutions

Some of these problems can be fixed by adhering to new standards as they come in, but a lot more might be solved by developers coming to the same conclusions about Web service development and changing their practices accordingly. Paying more attention to groups such as the WS-I and SOAPBuilders will definitely help.

A Freezing of Standards?

If organizations such as the WS-I are to succeed, they’ll need a stable base from which to work, so why not freeze the standards that represent the basic architecture once they come in line with SOAP 1.2? That gives the ones lagging behind (WSDL 1.2, UDDI) time to catch up and the toolkit developers time to liaise with each other and with interoperability groups to sort out issues. A time to stand back and collaborate is overdue; the various standards groups need this, and the WS-I needs it to produce a standard worth more than the paper it’s written on. Front-line developers could also focus on interoperation rather than stack alignment and marshaling details.

An interesting parallel exists here between WS-I and the Linux Standard Base (LSB) project (http://www.linuxbase.org/). The headache that LSB set out to alleviate was the increasing divergence in the content of the various Linux distributions that users can download (Red Hat, SuSe, Debian, and so on). A lot of extra effort was needed to accommodate new libraries and applications into the various distributions because they did not all contain the same compilers, graphics libraries, and so on. The LSB provided a reference set of packages for distributions to include. What’s interesting is that the various distributors saw the wisdom of adhering to the base and adopted it accordingly. Who’s to say that when the WSA or the WS-I’s base profile becomes a standard that vendors will adhere to them? If real collaboration is involved, there’s no reason why they wouldn’t. The effort required to talk it out would be outweighed by the value produced.

Coding Practices

Meanwhile, we developers still have to produce the cross-platform applications we’ve told the managers we can build, and that won’t get any easier unless we start following standard practices. DeveloperWorks has a nice set of articles identifying scenarios that best fit Web services (http://www-106. ibm.com/developerworks/webservices/library/ws-bestcol.html), but once you’ve realized that Web services are the way forward, where do you begin?

The .NET developer who just wants to create some private Web services for use internally can start off by adding the [WebMethod] attribute to a class method. A conscientious developer who doesn’t know what type of clients his Web service will attract has to start off with designing request and response messages, and that means writing a schema. Using an operating system–independent type system means that you can at least start off without any type clashes in your messages even if the data types contained within them are deserialized in slightly different ways. In .NET, that means using single-dimension arrays and avoiding datasets, using complex types defined by sequence or all and avoiding those defined by choice, and definitely avoiding substitution groups and object graphs. Have a look again at Chapter 6 to see what the Schema type system and .NET agree on. You’ve already seen how to implement a schema validator as a handler or SOAPExtension, so we have the added bonus of being able to validate messages as they come in and discard those that aren’t correct before they even finish their journey.

Once you design your schema, you need a WSDL document to wrap it in. All the toolkits can help you build a WSDL document around your service, but don’t be afraid to look at the results. Working with a toolkit is great, but unless you know what it’s doing (or not doing) for you, you’ll come to a screeching halt when you let it do too much. It’s like just working in design mode in Microsoft FrontPage and never looking at the HTML behind it. Don’t forget that you’re designing with commonality in mind, and your toolkit is writing your WSDL with just itself in mind. You might need to edit its efforts for the best results across the board. If you’ve had a good look at Chapter 3, you might even want to consider writing your own WSDL document from scratch.

One big difference among the WSDL produced by the various toolkits is the level of support the toolkits give to doc/literal and RPC/encoded-style messages. While it remains the default for some kits, RPC/encoded is quickly being recognized as a legacy style, supported for those who use Section 5 SOAP encoding. When SOAP 1.1 came out, most people saw SOAP as a simple RPC protocol that could easily work over the Internet with its firewalls and proxies. As a result, a rash of SOAP implementations mostly focused on RPC and on using Section 5 encoded messages. However, it’s become apparent that doc/literal is a better fit for SOAP messaging because you have full control over the format of the message payload through the use of schemas. You can even use schema validation as a security feature of sorts: the SOAP schema does allow anything to be placed in its <body> element, after all, even a virus or a Trojan horse.

There’s also the argument that it seems almost impossible to get RPC/encoded services working across every toolkit; the SOAPBuilders community has been trying for three years without much success. General thinking has it that RPC/encoded messages will slowly disappear in favor of doc/literal.

The key to making your services interoperable is to adhere to the standards as much as possible. Pay attention to details in the plumbing specs, and know what your toolkit does and doesn’t do.

Data-Oriented Design Practices

Beyond the quest for interoperability, you might want to match the way you design your Web service–powered applications with the way they will work, and not try to align the way they work with how you’re used to building applications. Normal class design goes out the window because the only exposed methods in your Web service API will be the Web methods.

The whole Web service architecture revolves around messages, or, if you want to view those messages as XML, data. You might serialize that data into and from objects, but Web services are not about objects. We continue to ignore the fact. .NET is object-oriented while Web services are message- or data-oriented.

The theory goes that if we start to design and build in the correct fashion, the need to comply with and eradicate ambiguities in standards and implementations will grow. The WS-I can help a lot in providing some simple tips to start you down the right road:

• Design messages, not methods. Start with the schema for your message and work outward, but don’t forget to keep things simple.

• Don’t try to reinvent the wheel. SOAP messages are XML, so make use of the XML vocabularies and standards that already exist. For example, why bother writing your own schema for a SQL query when you can place an XQuery in the body of the message and use the .NET extension classes for XQuery to execute them? Similarly, over 500 XML vocabularies are available for the various vertical markets out there. Why make your own if one already exists and is used by others? (Check out http://www.zapthink.com for a list.) Finally, don’t forget to look at what XHTML has to offer—it’s one of the most flexible XML vocabularies out there.

XML remains the key to working in this new fashion. It’s the basis for every piece of the W3C’s reference architecture and is data-oriented. Of course .NET, C++, and Java are still object-oriented, so will we ever be able to distance ourselves from the object-oriented paradigm? A company called Clear Methods saw this particular problem and siphoned (pun intended) a new, data-oriented language called Water that was designed specifically for Web service-based application development (http://www.waterlang.org). True to the nature of the problem, it’s even written in XML and can be validated with a schema. Water has been available since the beginning of 2002 and been well received by those up to the challenge. Given that it’s backed by Java, there’s still that question of translation between object-oriented and data-oriented code under the covers, but Microsoft will have to face this problem as well as it develops X# (http://www.microsoft-watch.com/article2/1,4248,766199,00.asp)—a .NET-based competitor for Water.