WSDL for Web Services documentation

XML is not enough to describe a web service, since it must also be based on some patterns; these patterns are provided by the WSDL description language, the elements of which will be explained in this chapter.

The XML schema alone cannot fully describe a Web Service. Suppose a Calculator Web service has been created. This Web service exposes the add and subtract methods. Both methods accept two integers and return a single integer with the result; add returns the sum of the two integers and subtract returns their difference.

In an effort to describe how a client interacts with the Web service, a schema is defined for the messages that will be exchanged between the client and the server. The schema contains a definition of a complex type for the request and response messages for the add and subtract methods. Remember that the ultimate goal is that developers don’t have to dig through schema definitions trying to figure out how to interact with the Web service. Instead you want to describe the service in such a way that a tool can decrypt it and create a proxy for the client.

In addition to the information provided by the schema, what else does the client need to know to call the methods exposed by the Calculator Web Service? Because the body of a SOAP message can contain anything that does not override XML, SOAP messages can be combined to have a wide variety of message exchange patterns. The message exchange patterns for the Calculator Web Service are fairly straightforward but a formal association between the Add and Subtract request messages and their associated response messages would remove any possible ambiguity.

A formal description of the message patterns becomes even more important in the case of more complex Web Services. Some services might accept a request but not send the corresponding response back to the client. Others might only send messages to the client.

Furthermore, the schema does not contain information on how to access the Web Service. Because SOAP is protocol independent, messages will be exchanged between the client and the server in numerous ways. How do you know if you need to send a message using HTTP, SMTP, or any other transport protocol? Furthermore, how do you know the address to which to send the message?

Web Service Description Language (WSDL) is an XML-based dialect of the schema that describes a Web service. A WSDL document provides the necessary information to the client to interact with the Web service. WSDL is extensible and can be used to describe virtually any network service, including SOAP over HTTP and even non-XML based protocols like DCOM over UDP.

Since communication protocols and message formats are standardized in the Web community, the possibility and importance of describing communications in a structured way increases every day. WSDL addresses this need by defining an XML grammar that describes network services as collections of communication endpoints capable of exchanging messages. WSDL service definitions provide documentation for distributed systems and serve as a formula for automating the details involved in communication between applications.

WSDL documents define services as collections of network endpoints or ports. In WSDL, the abstract definition of endpoints and messages is separated from the concrete installation of network or data format bindings. This allows the reuse of abstract definitions: messages, which are abstract descriptions of the data being exchanged, and port types, which are abstract collections of operations. The specific protocol and data format specifications for a given port type constitute a reusable binding. A port is defined by the association of a network address and a reusable link; a collection of ports defines a service. For this reason, a WSDL document uses the following elements in the definition of network services:

• Types: container of data type definitions used by some type system (for example XSD).
• Message: Abstract, written definition of the data being communicated.
• Operation: abstract description of an action supported by the service.
• Port Type: An abstract set of operations supported by one or more endpoints.
• Binding: specification of the protocol and data format for a particular type of port.
• Port – A single endpoint that is defined as the combination of a link and a network address.
• Service – Collection of related endpoints.

Each of these elements is detailed a little more in depth below.

element types

The Types element contains schema information referenced in the WSDL document. The default type system that WSDL supports is XML Schema. If XML schema is used to define the types contained in the Types element, the schema element will immediately appear as a child element.

Other extension type systems can be used. If you want to use another type system, an extensibility element can appear under the Types element. The name of this element should identify the type system used. In this chapter we will limit ourselves to XML schema because it is the dominant type system in WSDL documents.

message element

The Message element provides a common abstraction for message passing between the client and the server. Since you can use multiple schema definition formats in WSDL documents it is necessary to have a common mechanism to identify the messages. The Message element provides this common level of abstraction that will be referenced in other parts of the WSDL document.

There can and usually will be multiple Message elements in a WSDL document, one for each message that is communicated between the client and the server. Each message contains one or more “Part” elements that describe the pieces of the message content. An example of a part is the body of a SOAP message or a parameter that is part of a request string, a parameter encoded in the body of the SOAP message, or the entire body of a SOAP message.

portType element

The porType element contains a set of abstract operations that represent the types of mapping that can occur between the client and the server. For RPC-style Web Services you can think of a porType as a definition of internals where each method can be defined as an operation.

A port type is made up of a set of operation elects that define a certain action. The operation elects are composed of messages defined in the WSDL document. WSDL defines four types of operations called type operations:

• Request-response (request-response) RPC-type communication in which the client makes a request and the server sends the corresponding response.
• One-way (one-way) Document-style communication in which the client sends a message but does not receive a response from the server indicating the result of the processed message.
• Solicit-response(request-response) The opposite of the request-response operation. The server sends a request and the client sends back a response.
• Notification The opposite of the one-way operation, the server sends a document-style communication to the client.

binding element

The binding element contains the definitions of the association of a protocol such as SOAP to a certain bindingType. The binding definitions specify details of the message formats and the protocol. For example, the association information specifies whether an instance of a portType can be accessed in an RPC manner.

Binding definitions also indicate the number of network communications that are required to perform a certain action. For example, a SOAP over HTTP RPC call might involve one HTTP communication exchange, but that same call over SMTP might involve two discrete SMTP communication exchanges.

The association is accomplished using extension elements. Each protocol has its own set of extension elements to specify the details of the protocol and the format of the messages. For a given protocol, extension elements are often used to decorate the individual actions of an operation and the operation itself with the protocol’s association information. Sometimes extension elements are used at the portType level itself.

service element

A service is a group of related ports and they are defined in the service element. A port is a particular endpoint of a Web Service that is referenced by a unique address. The ports that are defined in a given service are independent. For example, the output of one port that cannot be used as an input of another.

Extensibility Elements

Extensibility elements are used to represent certain technologies. For example, extensibility elements can be used to specify the language used in the schema of the types elements.

The schema for a given set of extensibility elements must be defined within different namespaces than the WSDL. The definition of the elements themselves may contain a wsdl:required attribute indicating a boolean value if the requisited attribute is set to true in an element definition an association referencing that particular set of extensibility elects must include that element.

Most commonly, extensibility elements are used to specify association specification. The WSDL specification defines a set of extensibility elements for SOAP, HTTP GET, HTTP POS, MIME association. However, the specification only defines the associations for two of the four types of operations. A sense and request answered.