Project Management

Defining Web services in WSDL: A primer

When you're dealing with Web services, you need to be sure clients are using the data format the server expects. That's where the emerging WSDL standard comes in. This article gives you a guided tour of the basics of WSDL.

In a Web services world, applications basically consist of remote, XML-driven components written in different languages connected via the Web using a standard remote-activation protocol. Service authors need some way to define the data format required to use the service they provide. Similarly, when you look to consume a service in an application model such as this, you need a way to ensure that your client uses the data format expected by the server. This is the niche Web Services Definition Language (WSDL) was meant to fill.

WSDL in a nutshell
WSDL is a standard XML format for describing XML Web services, proposed by a group of vendors including Ariba, Intel, IBM, and Microsoft. It defines the set of operations and messages that can be sent to and received from a given Web service in an abstract, language-neutral manner. In that sense, you wouldn't be far off base to think of WSDL as a kind of object interface definition language, like that used for other component application architectures such as CORBA or COM. WSDL is also protocol-neutral, but it does have built-in support for binding to SOAP, making it rather irrevocably associated with it. With that in mind, as I discuss WSDL in this article, I'll assume you're using SOAP as your communication protocol.

WSDL has been submitted to the Internet-standards body World Wide Web Consortium (W3C), where its official status is that of Acknowledged Submission. W3C operates on a formal standardization system and attaches somewhat obscure status designations to submissions. In this case, WSDL's status, in layman's terms, means that it's under consideration to become at least part of a possible standard. If you are interested in that sort of thing, or happen to be an insomniac, you can read the proposed standard on the W3C Web site.

Describing services with WSDL
Being an XML-based standard, WSDL's structure will not be foreign to you if you have more than a passing knowledge of XML. A WSDL document consists of a set of elements that describe the data types used by the service, the "messages" the service may receive, and the SOAP bindings associated with each message.

You can get a look at a sample WSDL document in Listing A. This document is the same WSDL sample found on the W3C Web site and describes a stock quote Web service (pretty much the standard Web service example).

Looking at Listing A, you'll see that the document begins with the standard XML header containing a version identifier, and that the root element of the document is appropriately named definitions.

The definitions element can receive several optional attributes that describe it and define namespaces for use in the rest of the document. In this case, the definition is given a name (StockQuote), and some namespace definitions are made using the following conventional prefix abbreviations:
  • ·        tns—Short for "this namespace," the home namespace containing the service being defined
  • ·        xsdl—The XML Schema (XSD) namespace used to define types in the document
  • ·        soap—The namespace used for SOAP binding

Next, any complex types needed for the definition of the service's interface are defined inside the types element. Here you'll notice that standard XSD syntax (sans attributes) is used, which is the preferred method for creating data type definitions. However, WSDL can be extended to use a different type definition system, if you prefer.

There is a message for you
In WSDL parlance, a message can be any parameter passed to a method on an object the service exposes, or any result returned by the invocation of that method. To continue using the example of the stock quote Web service, the single defined method would likely be similar to the following pseudocode:
float getLastTradePrice(string tickerSymbol)

So, as you can see from Listing A, two messages were defined, one each to represent the method's input parameter tickerSymbol (the GetLastTradePriceInput message) and the return value of that method (the GetLastTradePriceResult message), the last trade price of the stock.

Operations group messages together and abstractly represent method definitions. The two messages used in our example are grouped into the definition for the getLastTradePrice object method in the GetLastTradePrice operation element. All operations in a WSDL document are in turn grouped inside a portType element.

The rest of a WSDL document is concerned with binding the messages with listener endpoints on the server (the binding element) and combining the port definitions into a single service entity (the service element). The example in Listing A defines the bindings needed to utilize the service over SOAP.

Tools for WSDL junkies
Although you certainly could create a WSDL document by hand, and it's bound to be useful for you to know how, quite a few tools are available that can automate the process of defining a Web service with WSDL. Some examples include:
  • ·        Omniopera—A GUI-based WSDL, XML, and XSD editor
  • ·        Microsoft's SOAP Toolkit—A toolkit that includes wizards for generating COM interfaces from WSDL definitions and for generating WSDL from COM interfaces
  • ·        IBM's Web Services Toolkit—A toolkit that includes a wizard to generate WSDL and SOAP deployment descriptors

Editor's Picks