Skip to content

Instantly share code, notes, and snippets.

@karanth

karanth/wsdl-pub.md

Created January 24, 2014 02:17
Show Gist options
  • Save karanth/8590949 to your computer and use it in GitHub Desktop.
Save karanth/8590949 to your computer and use it in GitHub Desktop.
Download ZIP
Notes on WSDL - Web Services Description Language
Raw
wsdl-pub.md

WSDL is an XML document that describes the contract a Web Service provides to its clients. The best way to explain a WSDL is by looking at XSD, or rules that govern the WSDL XML document. An example WSDL from the web is broken down and each element type is visited. The version of the WSDL below is 1.1. There is a newer 2.0 version of the WSDL XSD that has streamlined a few elements. However, Exchange Web Services still seem to be using 1.1. This particular Web Service gives stock quotes based on symbols.

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"       
                  xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
                  xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
                  xmlns:tns="http://www.webserviceX.NET/" 
                  xmlns:s="http://www.w3.org/2001/XMLSchema" 
                  xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" 
                  xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
                  targetNamespace="http://www.webserviceX.NET/">

The root element of a wsdl document is the node with the definitions tag. It specifies all the XML namespaces used in the document. XML namespaces are similar to programming language namespaces and are used to organize and qualify tags to avoid conflicts. The URI that follows a namespace name can be any url and the parser is not going to download the resource located at that place. By convention, the targetNamespace points to the current web service. The tns namespace definition is a duplicate of the targetNamespace. The soap namespace definition points to the SOAP specification.

<wsdl:types>
  <s:schema elementFormDefault="qualified" targetNamespace="http://www.webserviceX.NET/">
   <s:element name="GetQuote">
     <s:complexType>
       <s:sequence>
         <s:element minOccurs="0" maxOccurs="1" name="symbol" type="s:string"/>
       </s:sequence>
      </s:complexType>
   </s:element>
   <s:element name="GetQuoteResponse">
      <s:complexType>
         <s:sequence>
            <s:element minOccurs="0" maxOccurs="1" name="GetQuoteResult" type="s:string"/>
         </s:sequence>
      </s:complexType>
    </s:element>
  </s:schema>
</wsdl:types>

The types node is a container for all type definitions that are used by the methods of a Web Service. In the above example, even string, though it seems to be inside the GetQuote and GetQuoteResponse types, is defined as a type because it is used by an operation directly (will see later). The type attribute within a type definition gives the data type associated with that type. The nature of these data types, like string or boolean, are generally taken from the XML Schema definition document (the namespace indicates it) for seamless and universal interoperability. Strictly speaking, the data types can be from any language.

<wsdl:message name="GetQuoteSoapIn">
  <wsdl:part name="parameters" element="tns:GetQuote"/>
</wsdl:message>
<wsdl:message name="GetQuoteSoapOut">
  <wsdl:part name="parameters" element="tns:GetQuoteResponse"/>
</wsdl:message>

The messages nodes define the parameter lists for every operation. In a programming language setting, this can be viewed as the function parameters that appear in its signature. Here, for each parameter, there is a reference to the types that were defined earlier. The messages have to include both input as well as return parameters and their types.

<wsdl:portType name="StockQuoteSoap"> <wsdl:operation name="GetQuote"> <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">Get Stock quote for a company Symbol</wsdl:documentation> <wsdl:input message="tns:GetQuoteSoapIn"/> <wsdl:output message="tns:GetQuoteSoapOut"/> </wsdl:operation> </wsdl:portType> <wsdl:portType name="StockQuoteHttpGet"> <wsdl:operation name="GetQuote"> <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">Get Stock quote for a company Symbol</wsdl:documentation> <wsdl:input message="tns:GetQuoteHttpGetIn"/> <wsdl:output message="tns:GetQuoteHttpGetOut"/> </wsdl:operation> </wsdl:portType> <wsdl:portType name="StockQuoteHttpPost"> <wsdl:operation name="GetQuote"> <wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">Get Stock quote for a company Symbol</wsdl:documentation> <wsdl:input message="tns:GetQuoteHttpPostIn"/> <wsdl:output message="tns:GetQuoteHttpPostOut"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="StockQuoteSoap" type="tns:StockQuoteSoap"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="GetQuote"> <soap:operation soapAction="http://www.webserviceX.NET/GetQuote" style="document"/> wsdl:input <soap:body use="literal"/> </wsdl:input> wsdl:output <soap:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:binding name="StockQuoteSoap12" type="tns:StockQuoteSoap"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="GetQuote"> <soap12:operation soapAction="http://www.webserviceX.NET/GetQuote" style="document"/> wsdl:input <soap12:body use="literal"/> </wsdl:input> wsdl:output <soap12:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:binding name="StockQuoteHttpGet" type="tns:StockQuoteHttpGet"> <http:binding verb="GET"/> <wsdl:operation name="GetQuote"> <http:operation location="/GetQuote"/> wsdl:input http:urlEncoded/ </wsdl:input> wsdl:output <mime:mimeXml part="Body"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:binding name="StockQuoteHttpPost" type="tns:StockQuoteHttpPost"> <http:binding verb="POST"/> <wsdl:operation name="GetQuote"> <http:operation location="/GetQuote"/> wsdl:input <mime:content type="application/x-www-form-urlencoded"/> </wsdl:input> wsdl:output <mime:mimeXml part="Body"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="StockQuote"> <wsdl:port name="StockQuoteSoap" binding="tns:StockQuoteSoap"> <soap:address location="http://www.webservicex.net/stockquote.asmx"/> </wsdl:port> <wsdl:port name="StockQuoteSoap12" binding="tns:StockQuoteSoap12"> <soap12:address location="http://www.webservicex.net/stockquote.asmx"/> </wsdl:port> <wsdl:port name="StockQuoteHttpGet" binding="tns:StockQuoteHttpGet"> <http:address location="http://www.webservicex.net/stockquote.asmx"/> </wsdl:port> <wsdl:port name="StockQuoteHttpPost" binding="tns:StockQuoteHttpPost"> <http:address location="http://www.webservicex.net/stockquote.asmx"/> </wsdl:port> </wsdl:service> </wsdl:definitions>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment