Best Practices

Developers should also follow some basic best practices when building Web services. One of the most important concepts to understand about the WSF is that it is not a distributed object system. Web services communicate by exchanging messages - it's more like JMS than RMI. The WSF doesn't support remote references, remote object garbage collection, or any of the other distributed object features developers have come to rely upon in RMI, CORBA, or DCOM. The fundamental purpose of the WSF is to enable interoperability across dissimilar systems that don't necessarily understand concepts such as method overloading, object inheritance, and polymorphism. Hence Web service interfaces should not expose these OO concepts.

A service should expose a document-oriented interface rather than an object-oriented interface. The basic best practices are:

• Flatten object graphs. Don't expose language-specific object collections, such as maps, lists, or datasets. Instead convert all collections into arrays.
• Don't use overloaded methods. Each method should have a different operation name.
• Expose a "chunky" interface rather than a "chatty" interface. In other words, don't expose getter and setter operations for every member in the object class.

These best practices relate back to the differentiation between message exchange versus distributed object systems. When using distributed objects, the object resides on the server side, and the client invokes operations on the object using a proxy. The client does not have its own copy of the object. When using a message exchange system, the client side application should have its own object - not just a proxy. (And - by the way - the client's object may be different from the server's object.) When the client communicates with the server, it simply passes data, not behavior. It's much more loosely coupled.

It may be necessary to build an abstraction layer between the WSDL interface and the application that implements the service. This abstraction layer performs the necessary mapping between the document-oriented WSDL interface and the application's object model. It also provides much better insulation for flexibility and change.

For best interoperability, developers should use document/literal with the "wrapped" programming convention. .NET uses the "wrapped" style by default. The JAX-RPC specification also requires support for the "wrapped" style. The "wrapped" style supports a programming model that makes document/literal feel like RPC style. "Wrapped" style is very similar to RPC/literal, except for two important distinctions:

1. .NET supports "wrapped" style, but it doesn't support RPC/literal
2. "Wrapped" style defines a schema of the full soap body (which makes it very easy to validate), while RPC/Literal only defines type information rather that full element schemas (which makes validation slightly more complicated).

Please see my blog entry for a definition of the "wrapped" style: http://atmanes.blogspot.com/2005/03/wrapped-documentliteral-convention.html .

What About Advanced Features?

For the moment, interoperability is still very challenging when using advanced features. Basic security is progressing well, but standards for reliable messaging and transactions are still in flux.

Today, most developers rely on transport-level services to support advanced features. For example, a developer can use HTTP Basic Authentication and SSL to implement Web services security. These transport-level security capabilities are typically sufficient for point-to-point communications. Transport-level security doesn't provide sufficient protection, though, when messages need to be routed to multiple services or through one or more intermediaries. In these situations, developers should use message-level security based on WS-Security. Most vendors have added support for WS-Security to the latest versions of their products. Developers can also use a software-based Web services management (WSM) product or a hardware-based XML gateway product to automate the use of WS-Security. Developers should follow the guidelines defined in the WS-I Basic Security Profile (BSP) for using both transport-level and message-level security mechanisms.

For reliable messaging, most developers currently use a message queuing transport, such as IBM WebSphereMQ or SonicMQ. These systems support guaranteed message delivery, but they sacrifice pervasive communications. The message queuing system must be deployed on both sending and receiving nodes. Eventually, the WSF will support reliable messaging over HTTP based on WS-ReliableMessaging (WSRM). A handful of vendors (Blue Titan, Cape Clear, and Systinet) currently support WSRM, and many other vendors, including BEA, IBM, Microsoft, Sonic Software, and TIBCO, have implementations of WSRM in the lab. These vendors should release WSRM products before the end of 2005, and reliability should become a pervasive capability in the WSF within about eighteen months.

Transactions are a bit stickier. My general recommendation is not to use transactions with loosely coupled systems. Instead design the application to use reliable messaging to coordinate interdependent services. Nonetheless, some applications may require two phase commit (2PC) transaction integrity. IBM and IONA currently support WS-Transaction within their Web services platforms, and Arjuna and Choreology provide third party transaction coordinators that support WS-Transaction. A handful of other vendors have implementations of WS-Transaction in the lab, and we should see more product releases in 2006.

Transparent Infrastructure Nirvana

Today, if you want to use advanced features, you need to understand all of the associated WS-Vertigo specifications, but in the long run, this won't be the case. Once the WSF matures and these advanced capabilities become pervasive, the tooling will manage the infrastructure functionality automatically. Play with Microsoft's "Indigo" to get a sense of what it will be like. With "Indigo" a developer simply annotates her code to indicate that she wants to use security or reliable messaging. The "Indigo" compiler then automagically generates the appropriate runtime code and policies that ensure that the Web service uses WS-Security and WSRM. The Java community also plans to use code annotations in a similar way in the next release of JAX-RPC.

If you're a bleeding edge kind of developer, then have at it. Study the WS-Vertigo specifications to your heart's content. If you want to get your hands dirty, I suggest you play with the ws-fx projects being developed at Apache. But if you're just trying to get things done, then stick with the basics for the moment, and just don't worry about the WS-Vertigo specifications. The only specifications that you need to understand now are SOAP, WSDL, XML Schema, UDDI, and maybe WS-Security. And by all means follow the guidelines defined in the WS-I BP and BSP and stick with the best practices outlined above.