Selecting the Best Approach for Designing an Interoperable Web Service

CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Summary

Web Services technology is well established as a communication technology for the Internet, offering greatest interoperability. Their standardization process is going on at great speed, which will lead to even broader acceptance. Nevertheless, judging from mailing lists and user groups, discussions there say that there is still quite a lot of confusion about the different Web Services Design approaches. What does “Document/Literal” mean compared to “RPC-style?” How does SOAP “message-style” fit into this?

This article will clarify and explain in detail the different Web Service Design Methodologies as defined by the Web Services Standardization Groups, clarify the terms, and highlight their differences. It will be focus on the following Web Services Design Approaches evaluate their strengths and weaknesses and explore how far each style supports in designing an Interoperable Web Service.

  1. RPC/Encoded Style
  2. RPC/Literal Style
  3. Document/Literal Style
  4. Document/Literal Wrapped Style

Introduction

In their relatively short time of existence, Web Services have gained an enormous acceptance and a broad usage on the market. One reason for this surely is their very early open standardization that has been driven by all major players on the market. On the other side, all these players also have their preferences on how Web Services should look and how they should communicate. This, and the fact that different communication styles are required, has led to standards that today support different ways of how Web Services messages can be formatted and how they can communicate.

The relevant standards for describing and using Web Services are the Web Services Description Language (WSDL), a standardized XML Schema-like language that is used for specifying a Web Service and the Simple Object Access Protocol (SOAP), the actual communication protocol for Web Services ([WSDL] and [SOAP]).

Before moving to the real design approaches, let’s clarify some of the terms that are frequently used in the world of Web Services.

Communication Patterns

I’ll start with the communication patterns. With Web Services, you can essentially distinguish three different ways of communication:

  • Remote procedure call: Client sends a SOAP request to the service provider and then waits for a SOAP response (synchronous communication).
  • Messaging: Client sends a SOAP request and expects no SOAP response back (one-way communication)
  • Asynchronous callback: A client calls the service with one of the above methods. Later, the two parties switch roles for a callback call. This pattern can be built from either of the first two.

SOAP Formatting Rules

Now, you can turn to how the SOAP message of a Web Service can be formatted (essentially the message’s <soap:body> element). WSDL 1.1 distinguishes two different binding styles (referred to as soap:binding styles): RPC and Document.

  • RPC Style: The RPC style specifies that the <soap:body> contains an element with the name of the Web method being invoked (wrapper element). This element in turn contains an entry for each parameter and the return value of this method.
  • Document Style: If the style is of the document type, there is no wrapper element as with the RPC style. Instead, the message parts appear directly under the <soap:body> element. There are no SOAP formatting rules for what the <soap:body> contains; it contains what the sender and receiver agreed upon as an XML document.

The second formatting rule is the ‘Use‘ attribute. This concerns how types are represented in XML. It indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message. The two offered choices are:

  • Encoding: If the use is encoded, each message part references an abstract type using the type attribute. The message is produced using an encoding specified by the encodingStyle attribute. The mostly used SOAP Encoding is a set of serialization rules defined in SOAP 1.1. The rules specify how objects, structures, arrays, and object graphs should be serialized. In general, the applications using SOAP encoding are focused on remote procedure calls and will likely use the RPC message style.
  • Literal: If the use is Literal, each part references a concrete schema definition using either the element or type attribute; in other words, data is serialized according to a given schema. In practice, this schema is usually expressed using W3C XML Schema.

Table 1 summarizes the options for different Web Services parameters. An important realization is that three independent decisions are to be made by a Web Services developer. What is the “Communication Pattern” to be used? What is the SOAP formatting “Style” to be used? And finally, what is the SOAP message encoding Type to be used?

Table 1: Web Services Parameters

WSDL Parameters Available Options
Communication Patterns Remote Procedure Call or One-way messaging
Style Document or RPC
Use Encoded or Literal

Although, in theory, any combination of these options is possible, in practice there is a clear preference of one combination over the other, and also the standards and the Web Services Interoperability organization (WS-I) has a clear preference.

Thus, in practice, only Document/Literal and RPC/Encoded have gained widespread usage and are directly supported by most platforms as indicated in Table 2. The table shows also the results of the WS-I conformance tests for the different style/use combinations.

Table 2: Web Services Format Support

Style/Use Combination Supported SOAP Toolkit WS-I Conformance
RPC/Encoded Microsoft, Axis 1.1 Failed
RPC/Literal Axis 1.1 Failed
Document/Literal Microsoft, Axis 1.1 Passed

The Document/Encoded format has not been tested because it is not supported by the platforms used. In fact, there is no real-world usage of the Document/Encoded combination.

A Simple Web Service Example

Now, look in more detail into the mostly used and supported style/use formats RPC/Encoded and Document/Literal. I will illustrate each of these style use combinations by means of a Web method called “SendTemperature” that takes a user-defined complex object as its parameter and returns a void type, as described in Listing 1.

I chose an example with a complex data type to make the differences between the various styles more obvious.

Listing 1: SendTemperature Web method implemented in C#

public void SendTemperature (Temperature[] TempCollection){}

public class Temperature
{
   /// <remarks/>
   public int Id;

   /// <remarks/>
   public string Name;

   /// <remarks/>
   public System.Double Temperature;
}

You will see how the various Web Services formats are implemented in the WSDL file for this Web method with their respective SOAP request formats and their differences will be highlighted. The implementations were done using Microsoft VS.NET and the Axis SOAP toolkit.

Note that the namespaces, prefixes, and the service part of the WSDL files that follows in this article have been ignored for simplicity. Listing 2 shows the common namespaces and prefixes that were used.

Listing 2: Namespaces and used prefixes

xmlns_http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns_soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns_s="http://www.w3.org/2001/XMLSchema"
xmlns_s0="http://interop.webservices.fhso.ch/{service name}"
xmlns_soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns_tm="http://microsoft.com/wsdl/mime/textMatching/"
xmlns_mime="http://schemas.xmlsoap.org/wsdl/mime/"

targetNamespace="http://interop.webservices.fhso.ch/{service name}/"

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read