2009/09/07

WSDL 2.0: Quick reference

I wrote this blog entry mainly for me - to beat WSDL structure in my mind in a clean and nice way. Hopefully, it will help some others as well.

I would like to introduce changes between WSDL 1.1 and 2.0, and to go through the individual parts of the new WSDL version. This blog entry is based on several other on-line resources as well as books.

Introduction

WSDL stands for Web Services Description Language. It is a document written in XML. The document describes a Web service, specifies the location of the service, and the operations (or methods) the service exposes.

WSDL 2.0 was first developed as WSDL 1.2 but was renamed because of its substantial differences. Some major changes are:

  • Adding further semantics to the description language.
  • Removal of message constructs. These are specified using the XML schema type system in the types element.
  • No support for operator overloading.
  • PortTypes renamed to interfaces. Support for interface inheritance is achieved by using the extends attribute in the interface element.
  • Ports renamed to endpoints.

Conceptual Model

The description consists of two parts. In the abstract part, WSDL describes a web service in:

  • Messages it sends and receives using a type system (typically W3C XML Schema).
  • Message exchange patterns that define the sequence and cardinality of messages.
  • Operations that associates message exchange patterns with one or more messages.
  • Interfaces group these operations in a transport and wire independent manner.

In the concrete part of the description:

  • Bindings specify the transport and wire format for interfaces.
  • A service endpoint associates network address with a binding.
  • A service groups the endpoints that implement a common interface.

Structure

Following is a basic WSDL structure

<definitions targetNamespace="xs:anyURI">
<documentation /> ?
[<import /> | <include /> ] *
<types /> ?
[<interface /> | <binding /> | <service /> ] *
</definitions>

Definitions

The definitions element serves as a container.

<definitions name="StockQuote"
  targetNamespace="http://example.com/stockquote/definitions"
  xmlns:tns="http://example.com/stockquote/definitions"
  xmlns:xsd1="http://example.com/stockquote/schemas"
  xmlns:soap="http://www.w3.org/2003/11/wsdl/soap12"
  xmlns="http://www.w3.org/2003/11/wsdl">

Include

The include element helps to modularize the web service descriptions. Included documents must have the same target namespace.

Import

The concept behind the import element is very similar to that of include element, except that the imported WSDL can be in different target namespaces.

<import namespace="http://example.com/stockquote/schemas"
  location="http://example.com/stockquote/stockquoteV20.xsd"/>

Types

The types element defines the data types used by the exchanged messages. WSDL uses W3C XML Schema as its preferred schema language.

The following example refers to an imported XSD.

<types>
  <schema 
    targetNamespace="http://example.com/stockquote/definitions">
    <element name="GetLastTradePriceInput" 
      type="xsd1:TradePriceRequest"/>
    <element name="GetLastTradePriceOutput" 
      type="xsd1:TradePrice"/>
  </schema>
</types>

Interface

An interface element encloses a named set of abstract operations and the abstract messages. It can extend one or more other interfaces. Interfaces are referred to by QName in other components.

<interface name="StockQuoteInterface">
  <operation name="GetLastTradePrice" pattern="http://www.w3.org/2003/11/wsdl/in-out">
    <input message="tns:GetLastTradePriceInput"/>
    <output message="tns:GetLastTradePriceOutput"/>
  </operation>
</interface>

Binding

The binding element defines the underlying transport and wire format for messages. Each binding references to an interface.

<binding name="StockQuoteSoapBinding" 
  interface="defs:StockQuoteInterface">
  <soap:binding protocol="http://www.w3.org/2003/11/wsdl/http"/>
  <operation name="GetLastTradePrice">
    <soap:operation 
      soapAction="http://example.com/GetLastTradePrice"/>
    <input>
      <soap:body/>
    </input>
    <output>
      <soap:body/>
    </output>
  </operation>
</binding>

Service

A service element describes a set of endpoints which refer to a single network address for a binding. All other protocol specific information is contained in the binding.

<service name="StockQuoteService">
  <documentation>My stock quote service</documentation>
  <endpoint name="StockQuoteEndPoint" 
    binding="tns:StockQuoteSoapBinding">
    <soap:address location="http://example.com/stockquote"/>
  </endpoint>
</service>

Conclusion

Despite of the fact that the WSDL format might seem over-engineered to you (because it probably is), you should now be aware of its content and the meaning of individual elements.

References

[1] Article on WSDL at www.xml.com
[2] W3C School WSDL Tutorial
[3] Web Service Platform Architecture on InformIT.com

1 comment:

. .