A RESTFull WSDL?

In a recent comment, Paul mentions he is not familiar with the Document Style concept. This is a great opportunity to touch the theme and clarify some ideas about WSDL and the WSA idea of a service.

WSDL is meant to describe the service definition and interaction models. WSDL defines:

• The Service’s visible endpoint. That is, the address where the port of the service leaves.
• The Binding. That is, which transport to use and how.
• The Operations. Each operation with a name and a message flow (a named message inbound or outbound).
• The Messages. Each named message has a number of named parts that conform the payload.
• The Parts. Each one is defined either by indicating the primitive type or a schema defined xml.
• The Schema. A Types section that is defined using an XML schemas.

Using the above sections, we can define the service by indicating the port, the available operations, which message flow each operation has, and what is the structure of each message.

With the WSDL, the client is able to know how to construct the message and where to send it. So far so good for our service notion.

The problem comes when WSA came out with the style/encoding idea. SOAP was originally created to access Objects remotely (Simple Object Access Protocol). Here is the story.

Those were the times when RPC was the idea of remote access. So, SOAP was created a requirement for the body of the message. It had to be constructed with a fixed structure, where the root element’s name should be the same as the method name. The children elements should be one per parameter, and each one containing the type as an attribute. That structure was known as the encoding.

When WSA brought SOAP as the protocol to form the messages, it extended the idea in two directions. The first one was to allow some flexibility by defining a non-encoding format, and that was called “literal” (as opposite of “encoded”). The other direction is the style of the access. The RPC style is the original for SOAP, where the service is accessed by mimicking an RPC by indicating the method and parameters in the message and expect a response.
The other one is the Document Style. In this style, the idea is that the message contains a document (XML usually) that is delivered to the port.

The combination of style and encoding gives us four possibilities: RPC/Encoded (original RPC/SOAP style), RPC/Literal (A new RPC that is not that strict, see below), Document/Encoded (Nonsense), and Document/Literal (what all of us should use).

Now, let’s focus in RPC/Literal and Document/Literal. When defining the operations, the developer is able to indicate, per message, which style and encoding to use. If RPC/Literal is selected, the following rules apply:

• The body of the message is an XML with a root element whose name is the name of the operation.
• The children of that root element are the parameters, in order, for the implementing method.

A client calling a service’s operation defined as RPC/Literal, should create a message then that reassembles the structure of an RPC SOAP Message. The important thing here is that the XML in the body is created automatically with a root that has the operation name.

If Document/Literal is selected, the following rules apply.

• The body of the message is an XML document. No other restriction is given.

Note that with document/literal, there is no restriction of the body format. If by chance the root of that XML is not the name of the operation, it doesn’t matter. In reality, some of the vendors I tested, even if document style is indicated, will look for the name of the method to call in the first element of the body.

So, now imagine a service at port http://willyloans .com, that uses http, that has an operation called LoanRequest with one inbound message. That message is a one-part message, document style. That part is an XML document defined in the schema at Types section. The client should simply create a SOAP wrapper XML, and in the body element it will add the XML document (Payload). The client then simply sends that SOAP to the address defined in service (always using a post, WSA defined that).

That’s it. Using WSDL at document style, you can interact with the service just by sending a message containing a document, delivered to a port. NO method names nor parameters. That should be a RestFull call as Paul indicates, but with the help of WSDL that describes the flow, port and the XML document schema.

Hope this explanation helps.

William Martinez.

Reference and Comments: A RESTFull WSDL?