Chatterjee S., Webber J. Developing Enterprise Web Services. An Architect's Guide / Document, RPC, Literal, Encoded

Computers & Technology
Education & Reference
Business & Investing
Science & Math

Developing Enterprise Web Services. An Architect's Guide
Authors: Chatterjee S., Webber J.
Published year: 2003
Pages: 32-33/141

Buy this book on amazon.com >>

<< Previous page
Table of contents
Next page >>

Document, RPC, Literal, Encoded

Much of the confusion in understanding SOAP comes from the fact that several of the key terms are overloaded. For example, both SOAP RPC (meaning the convention for performing remote procedure calls via SOAP) and RPC style are both valid pieces of SOAP terminology. In this section we clarify the meaning of each of these terms so they do not cause further confusion as we begin discussing WSDL.

Document

Document-style SOAP refers to the way in which the application payload is hosted within the SOAP Body element. When we use document style, it means the document is placed directly as a child of the Body element, as shown on the left in Figure 3-22, where the application content is a direct child of the <soap:Body> element.

Figure 3-22. Document, RPC, Literal, and Encoded SOAP messages.

graphics/03fig22.gif

RPC

RPC-style SOAP wraps the application content inside an element whose name can be used to indicate the name of a method to dispatch the content to. This is shown on the right-hand side of Figure 3-22, where we see the application content wrapped <m:purchase> element.

Literal

Literal SOAP messages use arbitrary schemas to provide the meta-level description (and constraints) of the SOAP payload. Thus when using literal SOAP, we see that it is akin to taking an instance document of a particular schema and embedding it directly into the SOAP message, as shown at the top of Figure 3-22.

Encoded

SOAP-encoded messages are created by transforming application-level data structures via the SOAP Data Model into a XML format that conforms to the SOAP Schema. Thus, encoded messages tend to look machine-produced and may not generally resemble the same message expressed as a literal. Encoded messages are shown at the bottom of Figure 3-22.

SOAP RPC and SOAP Document-Literal

The SOAP specification provides four ways in which we could package SOAP messages, as shown in Figure 3-22. However, in Web services we tend to use only two of them: SOAP encoded-rpc (when combined with a request-response protocol becomes the SOAP RPC convention) and SOAP document-literal.

Document-literal is the preferred means of exchanging SOAP messages since it just packages application-level XML documents into the SOAP Body for transport without placing any semantics on the content.

As we have previously seen, with SOAP RPC the implied semantics are that the first child of the SOAP Body element names a method to which the content should be dispatched.

The remaining two options, document-encoded and rpc-literal, are seldom used since they mix styles to no great effect. Encoding documents is pointless if we already have schemas that describe them. Similarly, wrapping a document within a named element is futile unless we are going to use that convention as a remote procedure call mechanism. Since we already have SOAP RPC, this is simply a waste of effort.

SOAP, Web Services, and the REST Architecture

The World Wide Web (WWW) is unquestionably the largest and, by implication , the most scalable distributed system ever built. Though its original goal of simple content delivery was modest, the way that the Web has scaled is nothing short of miraculous .

Given the success of the Web, there is a body of opinion involved in designing the fundamental Web services architecture (that includes the SOAP specification) for which the means to achieving the same level of application scalability through Web services mirrors that of content scalability in the WWW.

The members of this group are proponents of the REST ( REpresentational State Transfer ) architecture, which it is claimed is "Web-Friendly." The REST architecture sees a distributed system as a collection of named resources (named with URIs) that support a small set of common verbs (GET, PUT, POST, DELETE) in common with the WWW.

The REST idea of defining global methods is similar to the UNIX concept of pipelining programs. UNIX programs all have three simple interfaces defined (STDIN, STDOUT, STDERR) for every program, which allows any two arbitrary programs to interact. The simplicity of REST as compared to custom network interfaces is analogous to the simplicity of UNIX pipelines vs. writing a custom application to achieve the same functionality. REST embraces simplicity and gains scalability as a result. The Web is a REST system, and the generic interfaces in question are completely described by the semantics of HTTP. ^[5]

^[5] See RESTwiki, http://internet.conveyor.com/RESTwiki/moin.cgi/FrontPage

What this means to the SOAP developer is that certain operations involving the retrieval of data without changing the state of a Web resource should be performed in a manner that is harmonious with the Web. For example, imagine that we want to retrieve the balance of our account from our bank Web service. Ordinarily we might have thought that something like that shown in Figure 3-23 would be ideal. If this message was sent as part of a HTTP POST, then it would be delivered to the SOAP server, which would then extract the parameters and deliver the results via the getBalanceResponse message.

Figure 3-23. A "Web-Unfriendly" message.

<?xml version="1.0" ?>

<env:Envelope

     xmlns:env="http://www.w3.org/2002/06/soap-envelope" >

  <env:Body>

    <bank:getBalance

  env:encodingStyle="http://www.w3.org/2002/06/soap-encoding"

  xmlns:bank="http://bank.example.org/">

      <bank:accountNo>

           12345678

      </bank:accountNo>

    </bank:getBalance>

  </env:Body>

</env:Envelope>

However, this is now discouraged by the SOAP specification and instead we are encouraged to use HTTP directly to retrieve the information, rather than "tunneling" SOAP through HTTP to get the information. A "Web-friendly" equivalent of Figure 3-23 is shown in Figure 3-24 where the HTTP request directly identifies the information to be retrieved and informs the Web service that it wants the returned information delivered in SOAP format.

Figure 3-24. A "Web-Friendly" message.

GET /account?no=12345678  HTTP/1.1

Host: bank.example.org

Accept: application/soap+xml

Figure 3-24 is certainly Web friendly since it uses the Web's application protocol (HTTP). However, there are a number of obstacles that have not yet been overcome at the time of writing that may prove detrimental to this approach:

A service may be exposed over other protocols than HTTP (e.g., SMTP that does not support the GET verb).
This scheme cannot be used if there are intermediate nodes that process SOAP header blocks.
There is no guidance yet provided by the SOAP specification authors on how to turn an RPC definition into its Web-friendly format.
Too much choice for little gain since we have to support the "Web-Unfriendly" approach anyway for those interactions that require the exchange of structured data.

While these techniques may yet come to fruition, it may be a long time before resolution is reached. When architecting applications today, the best compromise that we can offer is to be aware of those situations where you are engaged in pure information retrieval, and ensure that your architecture is extensible enough to change to a Web-friendly mechanism for those interactions tomorrow. Make sure the code that deals with Web services interactions is modular enough to be easily replaced by Web-friendly modules when the W3C architectural recommendations become more specific.