Basic Understanding of WSDL documents And How to Use a WSDL File to Access a SOAP Service

 What is WSDL?

 Web Service Description Language (WSDL).  These files are used to describe in great detail each web service and what operations it knows how to perform.  A WSDL file consists of several main sections:

- Services

 The service element(s) of a WSDL file defines a collection of ports, and points to a particular binding for each port.

 - Ports

 Ports are methods that can be used to access the service. 

- Bindings

 Each binding element of a WSDL file points to a corresponding port type and describes the data format and protocol for each (including a sneak peak at the operations).

 - PortTypes

 Each portType element of a WSDL file describes the operations that the service can implement.  Each operation description defines the input and output message that it uses.

- Messages

 The message elements of a WSDL file contain information about particular messages passed to and from a web service.  There are exactly one input and one output message for every operation.

 So each service (more than one can be defined in a WSDL file) can define one or more ports. Ports basically define how the service can be accessed.  The three most common ports at this point are SOAP, HTTP Get, and HTTP Post.  In this document, I am going to concentrate on the SOAP port.  Each port points to a binding, each binding points to a portType, and each portType defines the operations it can perform.  These operations can be anything from addition to supplying a stock quote.  Each of these operations then defines its input and output messages.

 So each piece of the file contains valuable information that will tell you how to use the service that it describes.

 Let’s take a look at an example service borrowed from www.xmethods.net.  Xmethods lists a domain name checker service that will determine if a particular domain name is available.  The WSDL for this particular service is located at http://services.xmethods.net/soap/urn:xmethods-DomainChecker.wsdl.

 First, let’s examine the <service> element:

<service name="net.xmethods.services.domainchecker.DomainCheckerService">
<documentation>net.xmethods.services.domainchecker.DomainChecker web service</documentation> 
<port name="net.xmethods.services.domainchecker.DomainCheckerPort" binding="tns:net.xmethods.services.domainchecker.DomainCheckerBinding"> 
<soap:address location="http://64.39.29.211:9090/soap" />
</port> 
</service>

 This service, named net.xmethods.services.domainchecker.DomainCheckerService contains one port definition (as well as a name) that points to a binding called (for short) DomainCheckerBinding.  The port definition also contains a soap:address location, which will be the end point URL we’ll use to access the service.  Make a note of this endpoint URL.

 Next, we can check out the binding that this service points us to.

<binding name ="net.xmethods.services.domainchecker.DomainCheckerBinding" type ="tns:net.xmethods.services.domainchecker.DomainCheckerPortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" /> 
<operation name="checkDomain"> 
<soap:operation soapAction="urn:xmethods-DomainChecker#checkDomain" /> 
<input>
<soap:body use="encoded" namespace="urn:xmethods-DomainChecker" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
</input> 
<output> 
<soap:body use="encoded" namespace="urn:xmethods-DomainChecker" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
</output>
</operation>
</binding> 

This binding defines one operation named checkDomain, which of course has an input and output message.  An important piece here is the method URI of each operation.  Notice the namespace="urn:xmethods-DomainChecker" .  This is the method URI for the operation checkDomain.  The binding includes a binding style, encoding style and transport protocol definition, and also a portType.  Let’s take a look at this portType.

<portType name ="net.xmethods.services.domainchecker.DomainCheckerPortType"> 
<operation name="checkDomain" parameterOrder="symbol"> 
<input message="tns:checkDomainRequest1" /> 
<output message="tns:checkDomainResponse1" /> 
</operation>
</portType> 

This portType (just like the binding) describes the operations and the operation input/output messages.  However, here rather than describing what encoding styles and transport methods to use, we see how to find the actual definitions of these messages. 

<input message="tns:checkDomainRequest1" />

This input message is called checkDomainRequest1.  Now we can go to the <message> element that corresponds with this message name and see exactly what it is.

<message name="checkDomainRequest1"> 
<part name="symbol" type="xsd:string" />
</message>

Here we can see that the Request message contains 1 part named symbol which is a string.  Each message can include more than one part or parameter.

Now through examining the WSDL file we have gathered some important pieces of information about this web service:

- End point URL

- Method URI

- The Operation that we want to perform, or Method name.

- Input parameters (messages)

So we are ready to use this information to form our SOAP request to access the service.  I am going to form this request with the IP*Works! SOAP component.  For those of you who are not familiar with this particular component you can download a fully functional free trial version at /n software. 

This component is made to be extremely easy to use.  All I have to do from here on is fill in the blanks with the information I have gathered:

    SOAP1.URL = http://64.39.29.211:9090/soap   â€˜The Endpoint URL
    SOAP1.MethodURI = "urn:xmethods-DomainChecker" â€˜The Method URI
    SOAP1.Method = "checkDomain"  ‘The Method Name
    SOAP1.AddParam "symbol", Microsoft.com  ‘The input message

Here I’ll use Microsoft.com as my symbol to perform the domain check on.  Now I simply send the request:

    SOAP1.SendRequest

 And retrieve the value from the SOAP1.ReturnValue property.

    Response.write Domain: + SOAP1.ReturnValue

 Here, the output I receive is:

 Domain: unavailable

 Now I can incorporate this service into my ASP application, .Net app, VB app, Delphi app, Java app, or whatever.

More Information

For information about the author, please contact lancer@nsoftware.com.

For more information about IP*Works! or the SOAPcomponent, please visit /n software.

Copyright © 2002, Lance Robinson - All Rights Reserved.  For publishing permissions, contact lancer@nsoftware.com.