SOAP

Properties of Traditional Web Service

• The web service is available on the Internet

• The web service uses a standardized XML messaging system

• The web service is not tied to any one operating system or programming language

• The web server is self-describing via a common XML grammar

• The web server is discoverable via a simple find mechanism

Web Service Protocol Stack

• Service Transport: layer responsible for transporting messages between applications

• XML Messaging: layer responsible for encoding messages in a common format

• Service Description: layer responsible for describing the public interface to a specific web service

• Service Discovery: layer responsible for centralizing services into a common registry

A Common Web Service Protocol Stack

• Service Transport: HTTP

• XML Messaging: Simple Object Access Protocol (SOAP)

• Service Description: Web Service Description Language (WSDL)

• Service Discovery: Universal Description, Discovery, and Integration (UDDI)

Simple Object Access Protocol (SOAP)

• A SOAP message is an XML document containing the following elements

  • Envelope: defines the start and end of the message

  • Header: contains optional attributes of the message

  • Body: contains the XML data comprising the message

  • Fault: an optional Fault element that provides information about errors that occur while processing the message

SOAP Message Format

<?xml version="1.0"?>
<example:Envelope xmlns:example="..."
      xmlns:encodingStyle="..." >

  <example:Header>
  ...
  </example:Header>

  <example:Body>
    ...
    <example:Fault>
    ...
    </example:Fault>
  </example:Body>

</example:Envelope>

SOAP Envelope Element

• The XML namespace attribute should always have the value:
  http://www.w3.org/2003/05/soap-envelop/

• The encodingStyle attribute is optional and is used to define the data types used in the document

SOAP Header Element

• The Header element is optional and if present must be the first child of the Envelope element and is intended for application specific information

• The mustUnderstand attribute is used to indicate whether a header child element is mandatory or optional for the recipient to process. A value of “1” is mandatory and a value of “0” is optional.

• The actor attribute is used to address the Header element to a specific endpoint. (A SOAP message may travel through multiple endpoints before arriving at the ultimate endpoint.)

• The encodingStyle attribute is optional and is used to define the data types used in the document

• Note: all children of the Header element must be namespace qualified

SOAP Body Element

• The encodingStyle attribute is optional and is used to define the data types used in the document

• Note: all children of the Body element must be namespace qualified

SOAP Fault Element

• The Fault element is optional and if present must be a child of the Body element

• The Fault element has the following child elements:

  • <faultcode>: a code for identifying the fault

  • <faultstring>: a human readable explanation of the fault

  • <faultactor>: information about the source of the fault

  • <detail>: application specific error information

• The <faultcode> values can be the following:

  • VersionMismatch: the namespace for the SOAP Envelope element is invalid

  • MustUnderstand: a child of the Header with a MustUnderstand attribute set to “1” was not understood

  • Client: the message was incorrectly formed

  • Server: there was a problem with the server

SOAP and HTTP

• A SOAP request using HTTP as the transport layer should have the following form:

  POST /item HTTP/1.1
  Content-Type: application/soap+xml; charset=utf-8
  Content-Length: bytes

  where item is the resource and bytes is the number of bytes of the SOAP message

Example SOAP Request

POST www.example.com/HasName HTTP/1.1
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>
<n:Envelope
xmlns:n="http://www.w3.org/2003/05/soap-envelope/"
n:encodingStyle="http://www.w3.org/2003/05/soap-encoding/">

<n:Body xmlns:m="http://www.example.com/name">
  <m:GetAge>
    <m:Name>Bob</m:Name>
  </m:GetAge>
</n:Body>

</n:Envelope>

Example SOAP Response

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>
<n:Envelope
xmlns:n="http://www.w3.org/2003/05/soap-envelope/"
n:encodingStyle="http://www.w3.org/2003/05/soap-encoding/">

<n:Body xmlns:m="http://www.example.com/name">
  <m:GetAgeResponse>
    <m:Age>18</m:Age>
  </m:GetAgeResponse>
</n:Body>

</n:Envelope>

Web Services Description Language (WSDL)

• An WSDL specifies the location of the service and the methods of the service

• An WSDL document using the following XML elements

  • <definitions>: the root element that defines the name of the web service

  • <types>: the data types used in the messages in the form of XML schemas

  • <message>: abstract definition of the data

  • <portType>: abstract set of operations

  • <binding>: concrete protocol and data formats for the operations and messages defined for a particular port type

  • <ports>: combination of a binding and a network address

  • <service>: collection of related endpoints

WSDL Document Structure

<definitions>
  <types>
    definition of types ...
  </types>
  <message>
    definition of a message ...
  </message>
  <portType>
    <operation>
      definition of an operation ...
    </operation>
  </portType>
  <binding>
    definition of a binding ...
  </binding>
  <service>
    definition of a service ...
  </service>
</definitions>

WSDL definitions element

• The definitions element is the root element and specifies the namespaces that are used throughout the document

• The definiitions element has the following attributes

  • name: specifies the name of the web service

  • targetNamespace: a convention of XML schema that enables the document to refer to itself

  • xmlns: specifies a default namespace for all elements in the document without a namespace prefix

WSDL types element

• The types element describes all the data types used between the client and the server

• The W3C XML Schema specification is the default choice to define data types

• Example:

  <types>
    <schema targetNamespace="..." xmlns="...">
      <element name="NameRequest">
        <complexType>
          <all>
            <element name="Name" type="string"/>
          </all>
        </complexType>
      </element>
    </schema>
  </types>

WSDL message element

• The message element describes all the data exchanged between the web service and its clients

• Each web service has two messages: input and output. The input describes the parameters and the output describes the return data

• Each message contains zero or more <part> parameters, which are associated with a concrete type defined in the <types> element.

• Example:

  <message name="HelloRequest">
    <part name="firstName" type="xsd:string"/> 
  </message>
  
  <message name="HelloResponse">
    <part name="greeting" type="xsd:string"/> 
  </message>

WSDL portType element

• The portType element combines multiple message elements to form a complete one-way or round-trip operation

• Example:

  <portType name="Hello_PortType">
    <operation name="hello">
      <input message="tns:HelloRequest"/>
      <output message="tns:HelloResponse"/>
    </operation>
  </portType>

• An optional <fault> element can be specified to encapsulate errors

WSDL Operation Types

• One-way: the operation can receive a message but will not return a response

• Request-response: the operation can receive a request and will return a response

• Solicit-response: the operation can send a request and will wait for a response

• Notification: the operation can send a message but will not wait for a response

WSDL binding Element

• The binding element provides specific details on how a portType operation will actually be transmitted over the wire

• The binding element has two attributes: name and type

• The following SOAP extensions elements allow specific details to be defined:

  • soap:binding – indicates the binding is available via SOAP. The style attribute indicates the SOAP message format and the transport attribute indicates the transport layer

  • soap:operation – indicates the binding of a specific operation to a specific SOAP implementation. The soapAction attribute specifies that the SOAPAction HTTP header be used

  • soap:body – specifies the details of input and output

WSDL binding Element Example

<binding name="Hello_Binding"
  type="tns:Hello_PortType>
  <soap:binding style="document"
    transport="http://schemas.xmlsoap.org/soap/http"/>
  <operation name="hello">
    <soap:operation soapAction="hello"/>
    <input>
      <soap:body encodingStyle="..."
        namespace="..."
        use="encoded"/>
    </input>
    <output>
      <soap:body encodingStyle="..."
        namespace="..."
        use="encoded"/>
    </output>
  </operation>
</binding>

WSDL port Element

• The port element defines an individual endpoint by specifying a single address binding

• Attributes:

  • name – provides a unique name among all ports defined in the

  • binding – refers to the binding using the linking rules defined by WSDL

• Example:

  <port binding="tns:Hello_Binding" 
    name="Hello_Port">
    <soap:address
      location="http://www.example.com/Hello"/>
  </port>

WSDL service Element

• The service element defines the ports supported by the web service

• The service element is a collection of ports

• Example:

  <service name="Hello_Service">
    <documentation>...</documentation>
    <port binding="tns:Hello_Binding" 
      name="Hello_Port">
      <soap:address
        location="http://www.example.com/Hello"/>
    </port>
  </service>

Universal Description, Discovery, and Integration (UDDI)

• UDDI is an XML-based standard for describing, publishing, and finding web services

• UDDI has two sections:

  • A registry of all web services’ metadata, including a pointer to the WSDL description of a service

  • A set of WSDL port type definitions for manipulating and searching that registry

• UDDI provides an Inquiry Interface for consumers to find a service and a Publisher Interface for service providers to list a service

UDDI Elements

Three types of information can be registered into a UDDI registry by a business or company:

• White Pages

  • Contain basic information about the company or business

  • Contact information

  • Unique identifiers for the company tax IDS

• Yellow Pages

  • Contain more details about the company including descriptions of the kind of electronic capabilities the company can offer

  • Uses common industrial categorization schemes, industry codes, product codes, etc.

• Green Pages

  • Contain technical information about a web service such as interfaces, URL locations, and discovery information

UDDI Data Structures

UDDI includes an XML Schema that describes the following data structures

• businessEntity – represents the provider of the web service

• businessService – represents an individual web service provided by the business entity

• bindingTemplate – the technical description of the web service

• tModel – way to describe the various business, service, and template structures stored in the UDDI registry

• publisherAssertion – a relationship structure associating two or more businessEntity structures according to a specific type of relationship

UDDI Inquiry Interface

• find_binding

• find_business

• find_ltservice

• find_tModel

• get_bindingDetail

• get_businessDetail

• get_businessDetailExt

• get_serviceDetail

• get_tModelDetail

• find_relatedBusiness

UDDI Publisher Interface

• get_authToken

• discard_authToken

• save_business

• save_service

• save_binding

• save_tModel

• delete_business

• delete_service

• delete_binding

• delete_tModel

• get_registeredInfo

• set_publisherAssertions

• add_publisherAssertions

• delete_publisherAssertions

• get_assertionStatusReport

• get_publisherAssertions