• A quick survey shows at least 32 specifications.

• Obviously, you aren't going to use them all to build simple web services.

• I claim you probably don't need most of them.

• There are two that you should be aware of:

  • WSDL - Web Service Description Language

  • SOAP - Simple Object Access Protocol

• SOAP and WSDL have multiple versions and SOAP has many "parts".

• You don't need these to develop a web service and I've shown this via the examples in class.

• SOAP is a vocabulary using the namespace http://www.w3.org/2003/05/soap-envelope for encoding messages.

• SOAP consists of mainly of three elements:

  • [soap:]Envelope - the document element that contains an optional [soap:]Header element followed by a required [soap:]Body element.

  • [soap:]Header - a wrapper for message "header" or "metadata" information elements.

  • [soap:]Body - a wrapper for the body of a message.

• The [soap:]Fault element can be used in the body as a standard way of sending/returning errors.

• You can put whatever you want in [soap:]Header and [soap:]Body.

1. You want to send "metadata" along with messages.

2. You need to send routing information.

3. You want to use the fault mechanisms of SOAP in error responses.

4. You need to send multiple documents and don't want to use multi-part POST mechanism.

5. You're doing RPC on the web and so you don't really have a document.

6. Someone else says you "must" use SOAP.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Body xmlns:t="http://www.smallx.com/services/tideinfo/2005">
<t:tidinfo location="9414290"/>
</soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Body xmlns:t="http://www.smallx.com/services/tideinfo/2005">
<t:tideinfo today='2005-04-11' high-at='01:18:00-07:00' low-at='07:54:00-07:00' location='9414290' xmlns:t='http://www.smallx.com/services/tideinfo/2005'><t:tide-data><t:tide-level level='5.45' time='00:00:00-07:00' date='2005-04-11'/>
<t:tide-level level='5.52' time='00:06:00-07:00' date='2005-04-11'/>
<t:tide-level level='5.58' time='00:12:00-07:00' date='2005-04-11'/>
<t:tide-level level='5.64' time='00:18:00-07:00' date='2005-04-11'/>
...
</t:tide-data>
</t:tideinfo>
</soap:Body>
</soap:Envelope>

• You do not need SOAP to implement and use web services!!!

• In the tideinfo examples, it is just extra syntax that serves no real purpose.

• For that kind of web service, it doesn't really hurt.

• It could even confuse users.

• Many web services "servers" and "frameworks" require that the message be wrapped with a SOAP envelope.

• WSDL: Web Services Description Language

• It is an XML vocabulary for describing web services.

• 1.0 was published independently in late 2000.

• 1.1 was published as a W3C note in 2001 (no working group).

• There is now a working group at the W3C that works on WSDL.

• 1.2 became 2.0 due to many changes in the structure/syntax.

• The 2.0 specification is still a working draft.

• A service is a group of ports.

• A port is a association of an endpoint (e.g. a URL) to a binding.

• A binding is a set of operations.

• A operation is a specification of input, output, and fault messages.

• A message is a set of XML elements where each element is a part of the message.

• Whew!

• We're going to develop a WSDL description of the tideinfo service.

• We only have one schema and one message to describe.

• There are lots of "features" of WSDL 1.1 we won't use.

• This example will show you the basics for an XML-in-XML-out web service.

• Service: tideinfo

• Port: The URL we expose it at.

• Binding: The single "get tide" request.

• Operation: The "get tide" request and response

• Messages: The tideinfo element (same for input & output).

• The document element is called [wsdl:]definitions in the http://schemas.xmlsoap.org/wsdl/ namespace.

• We'll use the 'name' attribute to give a common name for the tideinfo service:

  <wsdl:definitions name="tideinfo"
     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     targetNamespace="http://www.smallx.com/services/tideinfo/2005/wsdl"
     xmlns:service="http://www.smallx.com/services/tideinfo/2005/wsdl"
  >
     <wsdl:documentation xmlns="http://www.w3.org/1999/xhtml">
     <p>This service provides tide information by NOAA tide monitor location.</p>
     </wsdl:documentation>
  </wsdl:definitions>

• Inside this element is where all the descriptions of the messages/etc. go.

• The [wsdl:]documentation element is nice to use for descriptions of how to use the service or where to get more information.

• We can import the schema for the schema via the [wsdl:]import element:

  <wsdl:definitions ...>
  
  <wsdl:import namespace="http://www.smallx.com/services/tideinfo/2005" 
               location="http://www.smallx.com/tideinfo-service/tideinfo.xsd"/>
  
  </wsdl:definitions>

• This makes the element declarations and types available to the WSDL definitions.

• We have only one service:

  <wsdl:definitions ...>
  
  <wsdl:service name="tideinfo">
     <wsdl:port name="tideinfo-port" binding="service:tideinfo-binding"/>
  </wsdl:service>
  
  </wsdl:definitions>

• We've defined the port but referred to the [service:]tideinfo-binding binding.

• We need to define [service:]tideinfo-binding.

• The [service:]tideinfo-binding binding:

  <wsdl:definitions ...>
  
  <wsdl:binding name="tideinfo-binding">
     <wsdl:operation name="get-tides">
         <wsdl:input message="service:get-tides"/>
         <wsdl:output message="service:tides"/>
     </wsdl:operation>
  </wsdl:binding>
  
  </wsdl:definitions>

• We now need to define the messages.

• The messages:

  <wsdl:definitions ...>
  
  <wsdl:message name="get-tides">
     <part name="body" element="t:tideinfo"/>
  </wsdl:message>
  
  <wsdl:message name="tides">
     <part name="body" element="t:tideinfo"/>
  </wsdl:message>
  
  </wsdl:definitions>

• This service uses the same element for request and response.

<wsdl:definitions name="tideinfo"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   targetNamespace="http://www.smallx.com/services/tideinfo/2005/wsdl"
   xmlns:service="http://www.smallx.com/services/tideinfo/2005/wsdl"
>
   <wsdl:documentation xmlns="http://www.w3.org/1999/xhtml">
   <p>This service provides tide information by NOAA tide monitor location.</p>
   </wsdl:documentation>

<wsdl:import namespace="http://www.smallx.com/services/tideinfo/2005" 
             location="http://www.smallx.com/tideinfo-service/tideinfo.xsd"/>

<wsdl:message name="get-tides">
   <part name="body" element="t:tideinfo"/>
</wsdl:message>

<wsdl:message name="tides">
   <part name="body" element="t:tideinfo"/>
</wsdl:message>

<wsdl:binding name="tideinfo-binding">
   <wsdl:operation name="get-tides">
       <wsdl:input message="service:get-tides"/>
       <wsdl:output message="service:tides"/>
   </wsdl:operation>
</wsdl:binding>

<wsdl:service name="tideinfo">
   <wsdl:port name="tideinfo-port" binding="service:tideinfo-binding"/>
</wsdl:service>

</wsdl:definitions>

• What has this done for you?

• There is some metadata about the service.

• Where's the SOAP? (Mine is by the sink where it belongs!)

Is it really clean?

<wsdl:definitions name="tideinfo"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   targetNamespace="http://www.smallx.com/services/tideinfo/2005/wsdl"
   xmlns:service="http://www.smallx.com/services/tideinfo/2005/wsdl"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
>
   <wsdl:documentation xmlns="http://www.w3.org/1999/xhtml">
   <p>This service provides tide information by NOAA tide monitor location.</p>
   </wsdl:documentation>

<wsdl:import namespace="http://www.smallx.com/services/tideinfo/2005" 
             location="http://www.smallx.com/tideinfo-service/tideinfo.xsd"/>

<wsdl:message name="get-tides">
   <part name="body" element="t:tideinfo"/>
</wsdl:message>

<wsdl:message name="tides">
   <part name="body" element="t:tideinfo"/>
</wsdl:message>

<wsdl:binding name="tideinfo-binding">
   <soapbind:binding style="document"
                     transport="http://schemas.xmlsoap.org/soap/http"/>
   <wsdl:operation name="get-tides">
       <wsdl:input message="service:get-tides">
          <soap:body part="body" use="literal"/>
       </wsdl:input>
       <wsdl:output message="service:tides">
          <soap:body part="body" use="literal"/>
       </wsdl:output>
   </wsdl:operation>
</wsdl:binding>

<wsdl:service name="tideinfo">
   <wsdl:port name="tideinfo-port" binding="service:tideinfo-binding">
      <soap:address location="http://www.smallx.com/tideinfo-service/tideinfo.pd"/>
   </wsdl:port>
</wsdl:service>

</wsdl:definitions>