spacer


spacer
EBIEMBL-EBI Web Servicestutorials04_wsdl
Table of Contents

WSDL

Web Service Description Language

An important extension of SOAP 1) 2) is the use of service description documents using Web Service Description Language (WSDL) 3) 4). As well as documenting the service interface, the WSDL for a service provides an interface contract, which service providers strive to maintain, thus maintaining compatibility with older clients. Another advantage of of having a WSDL document describing a service is the availability of tools to generate client-side stub or server-side skeleton codes from the WSDL. This simplifies program development and also allow for the runtime discovery of services.

Given a WSDL service description tools such as soapUI provide a method for experimenting with the SOAP messages exchanges and the construction of test cases, by deriving the details of the SOAP messages from the information provided in the WSDL.

Anatomy

The WSDL document for a service defines the operations supported by a service and the formats for the messages required to invoke an operation and the message returned.

A WSDL 1.1 document has the following sections:

  • “types”: data structure types defined using XML Schema 5)
  • “message”: the messages to be exchanged
  • “portType”: abstract definition of the operations provided by the service
  • “bindings”: binding for the operations that describe how to encode the messages
  • “service”: description of the endpoint (URL) to send messages to

Types

To allow for complex types to be exchanged data types are defined using XML Schema, either directly in the “types” section of the document or in external documents imported into the WSDL.

From the EB-eye service, the types required for the listDomains operation: 

  <wsdl:types>
    <xsd:schema
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      attributeFormDefault="qualified"
      elementFormDefault="qualified"
      targetNamespace="http://www.ebi.ac.uk/EBISearchService">
      <xsd:element name="listDomains">
        <xsd:complexType/>
      </xsd:element>
      <xsd:complexType name="ArrayOfString">
        <xsd:sequence>
          <xsd:element maxOccurs="unbounded" minOccurs="0" name="string" nillable="true" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:element name="listDomainsResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element maxOccurs="1" minOccurs="1" name="arrayOfDomainNames" nillable="true" type="tns:ArrayOfString"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>

Messages

Abstract definitions of the messages that are exchanged when operations are called. These use the types defined earlier.

From the EB-eye service, the messages for the listDomains operation: 

  <wsdl:message name="listDomainsResponse">
    <wsdl:part name="parameters" element="tns:listDomainsResponse">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="listDomainsRequest">
    <wsdl:part name="parameters" element="tns:listDomains">
    </wsdl:part>
  </wsdl:message>

Services which use the document/literal wrapped SOAP style (e.g. EB-eye) are required to have one, and only one, part per message, and the part must have the name parameters 6). Some SOAP tool-kits treat document/literal and document/literal wrapped services slightly differently, thus being able to tell if a document/literal service is using the wrapped style can be useful when developing client software.

Port Type

Abstract definitions of the operations (methods) which are provided by the service. The inputs and outputs of the operations are defined using the messages defined earlier.

From the EB-eye service, the portType for the listDomains operation: 

  <wsdl:portType name="EBISearchService">
    <wsdl:operation name="listDomains">
      <wsdl:input name="listDomainsRequest" message="tns:listDomainsRequest">
    </wsdl:input>
      <wsdl:output name="listDomainsResponse" message="tns:listDomainsResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>

Binding

Unlike the operation definitions in the portType section the bindings define how the messages are exchanged (transport), formatted (style and use) and additional information about header information to be added to the message (e.g. SOAPAction). A WSDL may contain multiple bindings which use different “service” endpoints or alternative encodings.

The document/literal EB-eye service, has the following binding for the listDomains operation: 

  <wsdl:binding name="EBISearchServiceHttpBinding" type="tns:EBISearchService">
    <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="listDomains">
      <wsdlsoap:operation soapAction="urn:ListDomains"/>
      <wsdl:input name="listDomainsRequest">
        <wsdlsoap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="listDomainsResponse">
        <wsdlsoap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

Note the specification of the SOAP style using:

  • style=“document” in the wsdlsoap:binding element
  • use=“literal” in the wsdlsoap:body elements

The RPC/encoded WSDbfetch service, has the following binding for the getFormatStyles(db, format) operation: 

  <wsdl:binding name="WSDbfetchSoapBinding" type="impl:WSDBFetchServerLegacy">
    <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="getFormatStyles">
      <wsdlsoap:operation soapAction=""/>
      <wsdl:input name="getFormatStylesRequest">
        <wsdlsoap:body
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          namespace="http://wsdbfetch.ws.jdbfetch.ebi.ac.uk"
          use="encoded"/>
      </wsdl:input>
      <wsdl:output name="getFormatStylesResponse">
        <wsdlsoap:body
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          namespace="http://www.ebi.ac.uk/ws/services/WSDbfetch"
          use="encoded"/>
      </wsdl:output>
      <wsdl:fault name="DbfParamsException">
        <wsdlsoap:fault
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          name="DbfParamsException"
          namespace="http://www.ebi.ac.uk/ws/services/WSDbfetch"
          use="encoded"/>
      </wsdl:fault>
    </wsdl:operation>

Note the specification of the SOAP style using:

  • style=“rpc” in the wsdlsoap:binding element
  • use=“encoded” in the wsdlsoap:body elements

Service

The “service” defines where the messages are sent. As with the bindings a WSDL may contain multiple “service” definitions.

From the EB-eye service, the service for the listDomains operation: 

  <wsdl:service name="EBISearchService">
    <wsdl:port name="EBISearchServiceHttpPort" binding="tns:EBISearchServiceHttpBinding">
      <wsdlsoap:address location="http://www.ebi.ac.uk/ebisearch/service.ebi"/>
    </wsdl:port>
  </wsdl:service>

WSDL Examples

Document/literal WSDL

A listDomains() specific WSDL for the EB-eye service: 

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
  targetNamespace="http://www.ebi.ac.uk/EBISearchService"
  xmlns:ns1="http://webservice.ebinocle.ebi.ac.uk"
  xmlns:soapenc12="http://www.w3.org/2003/05/soap-encoding"
  xmlns:tns="http://www.ebi.ac.uk/EBISearchService"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:soapenc11="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <wsdl:types>
    <xsd:schema
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      attributeFormDefault="qualified"
      elementFormDefault="qualified"
      targetNamespace="http://www.ebi.ac.uk/EBISearchService">
      <xsd:element name="listDomains">
        <xsd:complexType/>
      </xsd:element>
      <xsd:complexType name="ArrayOfString">
        <xsd:sequence>
          <xsd:element maxOccurs="unbounded" minOccurs="0" name="string" nillable="true" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:element name="listDomainsResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element maxOccurs="1" minOccurs="1" name="arrayOfDomainNames" nillable="true" type="tns:ArrayOfString"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="listDomainsResponse">
    <wsdl:part name="parameters" element="tns:listDomainsResponse">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="listDomainsRequest">
    <wsdl:part name="parameters" element="tns:listDomains">
    </wsdl:part>
  </wsdl:message>
  <wsdl:portType name="EBISearchService">
    <wsdl:operation name="listDomains">
      <wsdl:input name="listDomainsRequest" message="tns:listDomainsRequest">
    </wsdl:input>
      <wsdl:output name="listDomainsResponse" message="tns:listDomainsResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="EBISearchServiceHttpBinding" type="tns:EBISearchService">
    <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="listDomains">
      <wsdlsoap:operation soapAction="urn:ListDomains"/>
      <wsdl:input name="listDomainsRequest">
        <wsdlsoap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="listDomainsResponse">
        <wsdlsoap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="EBISearchService">
    <wsdl:port name="EBISearchServiceHttpPort" binding="tns:EBISearchServiceHttpBinding">
      <wsdlsoap:address location="http://www.ebi.ac.uk/ebisearch/service.ebi"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

RPC/encoded WSDL

A getFormatStyles(db, format) specific WSDL for the WSDbfetch service: 

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
  xmlns:apachesoap="http://xml.apache.org/xml-soap"
  xmlns:impl="http://www.ebi.ac.uk/ws/services/WSDbfetch"
  xmlns:intf="http://www.ebi.ac.uk/ws/services/WSDbfetch"
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:tns1="http://exceptions.jdbfetch.ebi.ac.uk"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.ebi.ac.uk/ws/services/WSDbfetch">
  <wsdl:types>
    <schema
      xmlns="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://www.ebi.ac.uk/ws/services/WSDbfetch">
      <import namespace="http://exceptions.jdbfetch.ebi.ac.uk"/>
      <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
      <complexType name="ArrayOf_xsd_string">
        <complexContent>
          <restriction base="soapenc:Array">
            <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]"/>
          </restriction>
        </complexContent>
      </complexType>
      <complexType name="InputException">
        <sequence/>
      </complexType>
    </schema>
    <schema
      xmlns="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://exceptions.jdbfetch.ebi.ac.uk">
      <import namespace="http://www.ebi.ac.uk/ws/services/WSDbfetch"/>
      <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
      <complexType name="DbfException">
        <sequence/>
      </complexType>
      <complexType name="DbfParamsException">
        <complexContent>
          <extension base="tns1:DbfException">
            <sequence/>
          </extension>
        </complexContent>
      </complexType>
    </schema>
  </wsdl:types>
  <wsdl:message name="DbfParamsException">
    <wsdl:part name="fault" type="tns1:DbfParamsException"/>
  </wsdl:message>
  <wsdl:message name="getFormatStylesResponse">
    <wsdl:part name="getFormatStylesReturn" type="impl:ArrayOf_xsd_string"/>
  </wsdl:message>
  <wsdl:message name="getFormatStylesRequest">
    <wsdl:part name="db" type="xsd:string"/>
    <wsdl:part name="format" type="xsd:string"/>
  </wsdl:message>
  <wsdl:message name="getSupportedFormatsRequest">
  </wsdl:message>
  <wsdl:portType name="WSDBFetchServerLegacy">
    <wsdl:operation name="getFormatStyles" parameterOrder="db format">
      <wsdl:input message="impl:getFormatStylesRequest" name="getFormatStylesRequest"/>
      <wsdl:output message="impl:getFormatStylesResponse" name="getFormatStylesResponse"/>
      <wsdl:fault message="impl:DbfParamsException" name="DbfParamsException"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="WSDbfetchSoapBinding" type="impl:WSDBFetchServerLegacy">
    <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="getFormatStyles">
      <wsdlsoap:operation soapAction=""/>
      <wsdl:input name="getFormatStylesRequest">
        <wsdlsoap:body
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          namespace="http://wsdbfetch.ws.jdbfetch.ebi.ac.uk"
          use="encoded"/>
      </wsdl:input>
      <wsdl:output name="getFormatStylesResponse">
        <wsdlsoap:body
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          namespace="http://www.ebi.ac.uk/ws/services/WSDbfetch"
          use="encoded"/>
      </wsdl:output>
      <wsdl:fault name="DbfParamsException">
        <wsdlsoap:fault
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
          name="DbfParamsException"
          namespace="http://www.ebi.ac.uk/ws/services/WSDbfetch"
          use="encoded"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="WSDBFetchServerLegacyService">
    <wsdl:port binding="impl:WSDbfetchSoapBinding" name="WSDbfetch">
      <wsdlsoap:address location="http://www.ebi.ac.uk/ws/services/WSDbfetch"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>


Prev SOAP Next Web Service Registries
1) SOAP 1.1: http://www.w3.org/TR/soap11/
2) SOAP 1.2: http://www.w3.org/TR/soap12/
3) WSDL 1.1: http://www.w3c.org/TR/wsdl
4) WSDL 2.0: http://www.w3.org/TR/wsdl20/
5) XML Schema: http://www.w3c.org/XML/Schema
6) RPC/Literal and Freedom of Choice - http://msdn.microsoft.com/en-us/library/ms996466.aspx
 
tutorials/04_wsdl.txt · Last modified: 2012/11/30 15:22 (external edit)
spacer
spacer