Welcome!

Simeon Simeonov

Subscribe to Simeon Simeonov: eMailAlertsEmail Alerts
Get Simeon Simeonov via: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn


Related Topics: XML Magazine

XML: Article

Web Services Description Language

Web Services Description Language

It's time to look at the details of the Web Services Description Language (WSDL) specification and, in particular, how abstract information about Web services is represented in XML and which extensibility mechanisms enable the binding of abstract specifications to concrete implementations. We start with a quick review of the WSDL information model.

In the last XML in Transit (XML-J, Vol. 2, issue 2), we derived an information hierarchy for describing Web services by asking what, how, and where questions. The what question points us to the abstract specification of a Web service. The how question points us to a specific implementation of the abstract specification. The where question leads us to the location in which a specific implementation can be accessed.

We then looked at a WSDL information model for Web services descriptions and how it supports this information hierarchy. An abstract specification is defined by several concepts:

  • Type: Data type definitions in some type system usually but not limited to XML Schema.
  • Message: A unit of data being communicated. Messages can have any number of parts, and each part is associated with a type.
  • Operation: Description of an action supported by a Web service endpoint. An operation specifies the types of messages that are being exchanged and their interaction pattern, such as one-way, request-response, solicit-response, and notification.
  • Port type: Set of operations supported by a Web service endpoint.
The specific implementation of an abstract specification is defined via a binding, which specifies in detail how the abstract information is mapped to a specific representation in a given protocol. Bindings are comprehensive since they encompass ports, operations, and messages. Bindings also specify how types are represented on the wire. Currently, WSDL specifies bindings for SOAP 1.1, HTTP 1.1, and MIME.

Finally, associating a binding with a network address provides the location of the implementation. This is all that's needed to start communicating with a service endpoint. The notion of a Web service is simply a collection of related endpoints.

Therefore, the high-level view of the WSDL XML is pretty simple (see Listing 1). After that quick recap, let's dive into the details of the WSDL schema and bindings.

A Simple Example
Let's take the standard stock price look-up example we've used in the past and see how we can build a WSDL document for it. First we have to identify the data types that we're dealing with. Since the data is encoded in XML, it's best to use XML Schema as the type system. We define the element TradePriceRequest for the request message and the element TradePriceResponse for the output (see Listing 2).

Then we need to define the input and output messages. They each have only one part - their body (this is a simple example). We associate our schema types with the parts of the message using the element attribute of the part element. Note that we could have defined a fault message too.

<message name="GetLastTradePriceInput">
<part name="body" element="xsd1:TradePriceRequest"/>
</message>
<message name="GetLastTradePriceOutput">
<part name="body" element="xsd1:TradePriceResponse"/>
</message>

Next, we define the stock quote endpoint that has a single operation - GetLastTradePrice. The interaction pattern for the operation is request-response using the two previously defined messages.

<portType name="StockQuotePortType">
<operation name="GetLastTradePrice">
<input message="tns:GetLastTradePriceInput"/>
<output message="tns:GetLastTradePriceOutput"/>
</operation>
</portType>
This concludes the abstract specification of the stock price look-up service. We now define a concrete implementation by specifying a particular binding.

Bindings are defined per abstract endpoint. Therefore the structure of the binding XML mirrors that of the abstract endpoint - there will be an operation, and input and output messages. However, at every level we'll insert extensibility elements that correspond to a particular protocol (these are shown in bold in Listing 3). We'll use SOAP for the example.

We've defined a SOAP binding that uses HTTP (transport attribute of soap:binding element). Via the soap:operation element we provide a value for the SOAPAction header that will be passed through HTTP. We map both the input and output messages directly to the SOAP body using literal encoding. That's all we have to do for the binding.

Finally, we need to define a service by associating our binding with an address where stock quotes can be obtained. The actual association creates a concrete endpoint specified via the port element. For more complex scenarios, we could associate more than one endpoint with a service. This can involve more than one binding of the same abstract endpoint as well as bindings of different abstract endpoints.

<service name="StockQuoteService">
<documentation>Example stock quote service
<port name="StockQuotePort" binding="tns:StockQuoteBinding">
<soap:address location="{example}/stockquote"/>
</port>
</service>
The documentation element provides a simple description of the service and can be used liberally throughout the specification. Its content can be arbitrary text and elements.

Now that we've covered the basic structure of WSDL documents, let's look in more detail at the various possible bindings.

SOAP Binding
WSDL includes a binding to SOAP 1.1 that, among other things, allows for the following two-key protocol-specific capabilities:

  • Passes a URI for the SOAPAction HTTP header when SOAP is bound to HTTP
  • Defines what headers are transmitted as part of the SOAP envelope
The binding that's part of the WSDL spec is not meant to be complete. For example, SOAP can be bound to any number of protocols other than HTTP. This may require extensions to the SOAP binding that's presented with the WSDL spec.

What follows is a quick review of the SOAP extensibility elements. Instead of showing schema fragments to define the elements, I've borrowed a shorthand notation from the WSDL spec that uses regular expression syntax. The symbol "?" behind an element or attribute stands for zero or one occurrence; in other words, it makes the element or attribute optional. The symbol "*" denotes zero or more occurrences (see Listing 4).

We already saw an example of a SOAP binding. The purpose of the soap:binding element is to identify that the binding is to SOAP 1.1 and, via the transport attribute, to identify the transport that will be used with SOAP. Only HTTP has a value defined by the standard for now. The style attribute defines the default style for all operations in the binding.

The soap:operation element is used to define two things: the value of the SOAPAction header if HTTP is used and the style of the operation - document or RPC. Messages in document-oriented operations carry documents while those in RPC-oriented operations carry parameters and return values. The distinction is important in terms of parameter ordering.

The soap:body element specifies how message parts are included as part of the SOAP body element. The optional parts attribute determines which parts appear in the body. If it's omitted, all parts will appear in the body. The use attribute specifies whether the types passed through the message are abstract (and should therefore be encoded using a particular encoding style) or whether they reference a concrete schema (and can therefore be included literally in the SOAP body).

The soap:fault element specifies the contents of the SOAP fault details element that can be used to transmit additional error handling information. It follows the same rules as the soap:body element above.

The soap:header element allows headers to be defined as part of the SOAP messages. The element attribute refers to a concrete schema for the header element to be included in the SOAP message. The optional fault attribute defines a concrete schema for the header that's returned in case there's an error pertaining to header processing. (SOAP mandates that information related to errors in headers must be returned in headers.) The schemas can include definitions for soap:action, soap:mustUnderstand, and soap:encodingStyle.

Finally, soap:address provides a URI where a SOAP binding can be accessed.

HTTP Binding
WSDL includes a binding to HTTP 1.1 GET and POST operations. The following is a simple example of three HTTP bindings for a sample company information service. The input is a company ticker symbol. The output is defined in the next section. Listing 5 shows three different HTTP bindings that will be requested in the three different types of HTTP requests being made.

The first binding specifies URL encoding. In this case all message parts are put in a name-value format on the query string, for example, HTTP GET to ".../GetCompanyInfo?symbol=ALLR".

The second binding specifies URL replacement. In this case, the location URL is treated as a pattern in which all part names surrounded by parentheses are replaced with the URL-encoded values of the parts, for example, HTTP GET to ".../GetCompanyInfo/ALLR".

The third binding specifies an HTTP POST to "/GetCompanyInfo" in which all parts are passed through as MIME application/x-www-form-urlencoded, as if they were in a form field submitted by a browser, for example, HTTP POST to ".../CompanyInfo" with payload "symbol=ALLR".

MIME Binding
The MIME binding for WSDL defines a way to bind abstract types to MIME messages in the most common MIME formats: multipart/related (for mixed content), text/xml (the common case of XML), and application/x-www-form-urlencoded (HTML form submissions). Allowing custom content type strings supports other MIME types.

MIME binding extensibility elements can appear under the input and output WSDL elements. The following example shows a WSDL fragment defining an output message for the company information Web service in the MIME multipart/related format. The message consists of several parts: an XML document (some structured company information), an HTML company overview, and a company logo in either GIF or JPEG format (more than one MIME content type for a given part are treated as alternatives). Note that the SOAP extensibility element soap:body can be mixed in with the MIME extensibility elements to specify that a SOAP message is part of the MIME packet.

<output>
<mime:multipartRelated>
<mime:part>
<mime:mimeXml
part="info"/>
</mime:part>
<mime:part>
<mime:content part="docs"
type="text/html"/>
</mime:part>
<mime:part>
<mime:content part="logo"
type="image/gif"/>
<mime:content part="logo"
type="image/jpeg"/>
</mime:part>
</mime:multipartRelated>
</output>
This is pretty much all there is to WSDL. True, I skipped some details about authoring modular WSDL specifications and I didn't delve into the intricacies of RPC-oriented versus document-oriented messages. Nor did I discuss the strategies and rules for encoding abstract types. That's what the spec is for. We don't have time to hang around here any more. The higher levels of the Web service interoperability stack await us. In the next XML in Transit we'll build a conceptual framework for using Web services.

More Stories By Simeon Simeonov

Simeon Simeonov is CEO of FastIgnite, where he invests in and advises startups. He was chief architect or CTO at companies such as Allaire, Macromedia, Better Advertising and Thing Labs. He blogs at blog.simeonov.com, tweets as @simeons and lives in the Greater Boston area with his wife, son and an adopted dog named Tye.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.