WebServices HandBook

Updated 09/15/2006

What is Web Service?

According to W3C.org “A Web service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the Web service in a manner prescribed by its description using SOAP messages, typically conveyed using HTTP with an XML serialization in conjunction with other Web-related standards”

The purpose of a Web service is to provide some functionality on behalf of its owner -- a person or organization, such as a business or an individual. The provider entity is the person or organization that provides an appropriate agent to implement a particular service.

A requester entity is a person or organization that wishes to make use of a provider entity's Web service. It will use a requester agent to exchange messages with the provider entity's provider agent.

Figure: The general process of engaging a Web Service

What You Should Already Know

Before you continue you should have a basic understanding of the following:

  • XML
  • XML Namespaces
  • XML Schema

WebService Document Structure:

Definition documents act as underlying structure for a service description:

Combination of abstract and concrete WSDL makes Service Definition for a Web Service.

Abstract:

The description of a web service interface, independent of implementation details, is referred to as the abstract.

Concrete:

Specific location and implementation information about a Web Service are the Concrete parts of a WSDL document, as represented by the binding, service and endpoint (or port) elements.

Service Definitions:

Generally, the contents of a WSDL document constitute a service definition, which includes the interface and implementation definitions.

Service Descriptions:

Often a service description consists of only a WSDL document providing a service definition; however, it can include a number of additional definition documents that can provide supplemental information

Sample of a SOAP Message over HTTPS Transport:

Using the HTTP binding with the SOAP Request-Response message exchange pattern is restricted to the HTTP-POST method.

SOAP Request Message:

HTTP Method --> POST: /MDTPublic.serviceagent/ParticularESIIDs HTTP/1.1
Host Information --> Host: ercot.webservices.com
Type --> Content-Type: application/soap+xml || text/xml; charset="utf-8"
Size --> Content-Length: 634
Credentials  <Context</Context>
Posted SOAP Message:
<?xml version='1.0'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=" >
<SOAP-ENV:Body>
<ParticularESIIDs App = "AA" Source = "gui"
xmlns = "
xsi:schemaLocation=" ../../ProjectResource/Schema/InterfaceXSD/MarketDataTransparency.xsd">
<IdType>ESIID</IdType>
<PitsDate>2006-08-27</PitsDate>
<ResultFormat>CSV</ResultFormat>
<ReturnType>ESH_ESIID</ReturnType>
<ExtractIDUpload>
<ESIID>10032789444844617</ESIID>
</ExtractIDUpload>
</ParticularESIIDs>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the above sample message, The SOAP message is sent in the body of a HTTP Post method directed at the URI Identifying the resource “MDTPublic.serviceagent/ParticularESIIDs” on the server host “ercot.webservices.com”. When using HTTP, the Request-URI indicates the resource to which the invocation is "posted".

When placing SOAP messages in HTTP bodies, the HTTP Content-type header must either be chosen as "application/soap+xml" or “text/xml”. (The optional charset parameter, which can take the value of "utf-8" or "utf-16")

The Digital certificate information will be included as part of the HTTP Request in the Header (The Context tree would be containing the credentials information while posting the message to the service provider)

SOAP Response Message:

Response Code -- > HTTP/1.1 200 OK
Type --> Content-Type: application/soap+xml; charset="utf-8"
Size --> Content-Length: 100
Received SOAP Response Message:
<?xml version='1.0'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=" >
<SOAP-ENV:Body>
<ScheduleDataRequestResponse
xmlns:SOAP-ENV = "
xmlns = "
<AuditId>2047</AuditId>
<Status>INITIALIZED</Status>
<Response>
<ResponseStatus>SUCCESS</ResponseStatus>
<ResponseDateTime>2006-07-27T14:36:52.71-05:00</ResponseDateTime>
</Response>
</ ScheduleDataRequestResponse >
</SOAP-ENV:Body>
</SOAP-ENV>

In the above message, SOAP using HTTP Transport, follows the semantics of the HTTP status for communicating status information in HTTP. The Status code 200 in the above message indicated that the client’s request was successfully received, processed, and returned.

Introduction to WSDL

WSDL is an XML-based language for describing Web services and how to access them. It is described through a stack of definition documents that constitute a service

What is WSDL?

  • WSDL stands for Web Services Description Language
  • WSDL is written in XML
  • WSDL is an XML document
  • WSDL is used to describe Web services
  • WSDL is also used to locate Web services

WSDL Documents

A WSDL document is just a simple XML document.

It contains set of definitions to describe a web service.

The WSDL Document Structure

A WSDL document describes a web service using these major elements:

Element / Defines
<portType> / The operations performed by the web service
<message> / The messages used by the web service
<types> / The data types used by the web service
<binding> / The communication protocols used by the web service

The main structure of a WSDL document looks like this:

<definitions>
<types>
definition of types......
</types>
<message>
definition of a message....
</message>
<portType>
definition of a port......
</portType>
<binding>
definition of a binding....
</binding>
</definitions>

A WSDL document can also contain other elements, like extension elements and a service element that makes it possible to group together the definitions of several web services in one single WSDL document.

WSDL Ports (Interface)

The <portType> element is the most important WSDL element.

It describes a web service, the operations that can be performed, and the messages that are involved.

The <portType> element can be compared to a function library (or a module, or a class) in a traditional programming language.

WSDL Messages

The <message> element defines the data elements of an operation.

Each message can consist of one or more parts. The parts can be compared to the parameters of a function call in a traditional programming language.

WSDL Types

The <types> element defines the data types that are used by the web service.

For maximum platform neutrality, WSDL uses XML Schema syntax to define data types.

WSDL Bindings

The <binding> element defines the message format and protocol details for each port.

WSDL Example

Sample of a WSDL Message structure with operations defined;

<wsdl:definitions targetNamespace = " xmlns:ns0 = " xmlns:soap = " xmlns:soap1 = " xmlns:tns = " xmlns:wsdl = " xmlns:xs = "
<wsdl:types>
<schema attributeFormDefault = "unqualified" elementFormDefault = "qualified" targetNamespace = " xmlns = " xmlns:MDT = "
<element name = "IDRUsageESIIDs" type = "SCR727:IDRUsageESIIDsType">
<annotation>
<documentation>Provide IDR usage data for particular ESIIDs I own</documentation>
</annotation>
</element>
</schema>
</wsdl:types>
<wsdl:message name = "IDRUsageESIIDsRequest">
<wsdl:part element = "MDT:IDRUsageESIIDs" name = "request"/>
</wsdl:message>
<wsdl:portType name = "Operations">
<wsdl:operation name = "IDRUsageESIIDs">
<wsdl:input message = "tns:IDRUsageESIIDsRequest"/>
<wsdl:output message = "tns:CommonResponse"/>
<wsdl:fault message = "tns:FaultMessage" name = "fault"/>
</wsdl:operation>
<wsdl:operation name = "AggregationRecords">
<wsdl:input message = "tns:AggregationRecordsRequest"/>
<wsdl:output message = "tns:CommonResponse"/>
<wsdl:fault message = "tns:FaultMessage" name = "fault"/>
</wsdl:operation>
<wsdl:operation name = "ProvideESIIDForLogicalKeys">
<wsdl:input message = "tns:ProvideESIIDForLogicalKeysRequest"/>
<wsdl:output message = "tns:CommonResponse"/>
<wsdl:fault message = "tns:FaultMessage" name = "fault"/>
</wsdl:operation>
<wsdl:operation name = "GetDataRequestDetails">
<wsdl:input message = "tns:GetDRDetailsRequest"/>
<wsdl:output message = "tns:GetDRDetailsResponse"/>
<wsdl:fault message = "tns:FaultMessage" name = "fault"/>
</wsdl:operation>
</wsdl:portType>

In this example the <wsdl:definitions> defines the namespaces used in this WSDL. <wsdl:types> define the data types used in this service definitions. The <wsdl:portType> element defines "Operations" as the name of a port, and "IDRUsageESIIDs" as the name of an operation.

The "IDRUsageESIIDs" operation has an input message called "IDRUsageESIIDsRequest" and an output message called "CommonResponse".

The <wsdl:message> elements define the parts of each message and the associated data types (most of the times as XSDs).

Compared to traditional programming, Operations is a function library, "IDRUsageESIIDs" is a function with "IDRUsageESIIDsRequest" as the input parameter and CommonResponse as the output parameter.

WSDL Ports

A WSDL port describes the interfaces (legal operations) exposed by a web service.

WSDL Ports

The <portType> element is the most important WSDL element.

It defines a web service, the operations that can be performed, and the messages that are involved.

The port defines the connection point to a web service. It can be compared to a function library (or a module, or a class) in a traditional programming language. Each operation can be compared to a function in a traditional programming language.

Operation Types

The request-response type is the most common operation type, but WSDL defines four types:

Operation messages are represented by message constructs that are declared separately under the definitions element. The message names then are referenced in the operation’s input or output child elements.

Type / Definition
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

One-Way Operation

A one-way operation example:

<message name="newTermValues">
<part name="term" type="xs:string"/>
<part name="value" type="xs:string"/>
</message>
<portType name="glossaryTerms">
<operation name="setTerm">
<input name="newTerm" message="newTermValues"/>
</operation>
</portType >

In this example the port "glossaryTerms" defines a one-way operation called "setTerm".

The "setTerm" operation allows input of new glossary terms messages using a "newTermValues" message with the input parameters "term" and "value". However, no output is defined for the operation.

Request-Response Operation

A request-response operation example:

<wsdl:message name = "IDRUsageESIIDsRequest">
<wsdl:part element = "MDT:IDRUsageESIIDs" name = "request"/>
</wsdl:message>
<wsdl:message name = "CommonResponse">
<wsdl:part element = "MDT:ScheduleDataRequestResponse" name = "response"/>
</wsdl:message>
<wsdl:message name = "FaultMessage">
<wsdl:part element = "MDT:Fault" name = "PR50024Fault"/>
</wsdl:message>
<wsdl:portType name="Operations">
<wsdl:operation name="IDRUsageESIIDs">
<wsdl:input message="tns:IDRUsageESIIDsRequest"/>
<wsdl:output message = "tns:CommonResponse"/>
<wsdl:fault message = "tns:FaultMessage" name = "fault"/>
</wsdl:operation>
</wsdl:portType>

In this example the port "Operations" defines a request-response operation called "IDRUsageESIIDs".

The "IDRUsageESIIDs" operation requires an input message called "IDRUsageESIIDsRequest" with a part element called "IDRUsageESIIDs", and will return an output message called "CommonResponse" with a part element called "ScheduleDataRequestResponse". If there is an error, then the fault message will be generated by using the part called “Fault”

WSDL Bindings

WSDL bindings define the message format and protocol details for a web service.

WSDL includes a binding for SOAP 1.x endpoints, which supports the specification of the following protocol specific information:

  • An indication that a binding is bound to the SOAP 1.x protocol.
  • A way of specifying an address for a SOAP endpoint.
  • The URI for the SOAPAction HTTP header for the HTTP binding of SOAP.
  • A list of definitions for Headers that are transmitted as part of the SOAP Envelope

A request-response operation example:

<wsdl:binding name = "IDRUsageESIIDsBinding" type = "tns:Operations">
<soap:binding style = "document" transport = "
<wsdl:operation name = "IDRUsageESIIDs">
<soap:operation soapAction = "/BusinessService/ES/Public/PR50024Public.serviceagent/OperationsEndpoint11/IDRUsageESIIDs" style = "document"/>
<wsdl:input>
<soap:body parts = "request" use = "literal"/>
</wsdl:input>
<wsdl:output>
<soap:body parts = "response" use = "literal"/>
</wsdl:output>
<wsdl:fault name = "fault">
<soap:fault name = "fault" use = "literal"/>
</wsdl:fault>
</wsdl:operation>

The binding element has two attributes - the name attribute and the type attribute.

The name attribute (you can use any name you want) defines the name of the binding, and the type attribute points to the port for the binding, in this case the "Operations" port.

The soap:binding element has two attributes - the style attribute and the transport attribute.

The style attribute can be "rpc" or "document". In this case we use document. The transport attribute defines the SOAP protocol to use. In this case we use HTTP.

The operation element defines each operation that the port exposes.

For each operation the corresponding SOAP action has to be defined. You must also specify how the input and output are encoded. In this case we use "literal".

WSDL Service Implementation

The service element defines the ports supported by the Web service. For each of the supported protocols, there is one port element. The service element is a collection of ports.

A service implementation sample:

<wsdl:service name = "PR50024ExternalPublic">
<wsdl:port binding = "tns:IDRUsageESIIDsBinding" name = "IDRUsageESIIDs">
<soap:address location = "
</wsdl:port>
</wsdl:service>

In the above mentioned sample, the binding attributes associate the service with a binding element (which we discussedearlier). In case of this sample, the binding attribute of service PR50024ExternalPublic associated with the binding element “IDRUsageESIIDsBinding”

<soap:address> element defines the location of the service provider’s host. In case of this sample, it is being pointed to “

WSDL and UDDI

Universal Description, Discovery and Integration (UDDI) is a directory service where businesses can register and search for Web services.

What is UDDI

UDDI is a platform-independent framework for describing services, discovering businesses, and integrating business services by using the Internet.

  • UDDI stands for Universal Description, Discovery and Integration
  • UDDI is a directory for storing information about web services
  • UDDI is a directory of web service interfaces described by WSDL
  • UDDI communicates via SOAP
  • UDDI is built into the Microsoft .NET platform

What is UDDI Based On?

UDDI uses World Wide Web Consortium (W3C) and Internet Engineering Task Force (IETF) Internet standards such as XML, HTTP, and DNS protocols.

UDDI uses WSDL to describe interfaces to web services

Additionally, cross platform programming features are addressed by adopting SOAP, known as XML Protocol messaging specifications found at the W3C Web site.

UDDI Benefits

Any industry or businesses of all sizes can benefit from UDDI

Before UDDI, there was no Internet standard for businesses to reach their customers and partners with information about their products and services. Nor was there a method of how to integrate into each other's systems and processes.
Problems the UDDI specification can help to solve:

  • Making it possible to discover the right business from the millions currently online
  • Defining how to enable commerce once the preferred business is discovered
  • Reaching new customers and increasing access to current customers
  • Expanding offerings and extending market reach
  • Solving customer-driven need to remove barriers to allow for rapid participation in the global Internet economy
  • Describing services and business processes programmatically in a single, open, and secure environment

How can UDDI be Used

If the industry published an UDDI standard for flight rate checking and reservation, airlines could register their services into an UDDI directory. Travel agencies could then search the UDDI directory to find the airline's reservation interface. When the interface is found, the travel agency can communicate with the service immediately because it uses a well-defined reservation interface.

Who is Supporting UDDI?

UDDI is a cross-industry effort driven by all major platform and software providers like Dell, Fujitsu, HP, Hitachi, IBM, Intel, Microsoft, Oracle, SAP, and Sun, as well as a large community of marketplace operators, and e-business leaders.

Over 220 companies are members of the UDDI community.

The Full WSDL Syntax

The full WSDL 1.2 syntax as described in the W3C Working Draft is listed below.

<wsdl:definitions name="nmtoken"? targetNamespace="uri">

<import namespace="uri" location="uri"/> *

<wsdl:documentation .... /> ?

<wsdl:types> ?

<wsdl:documentation .... /> ?

<xsd:schema .... /> *

</wsdl:types>

<wsdl:message name="ncname"> *

<wsdl:documentation .... /> ?

<part name="ncname" element="qname"? type="qname"?/> *

</wsdl:message>

<wsdl:portType name="ncname"> *

<wsdl:documentation .... /> ?

<wsdl:operation name="ncname"> *

<wsdl:documentation .... /> ?

<wsdl:input message="qname"> ?

<wsdl:documentation .... /> ?

</wsdl:input>

<wsdl:output message="qname"> ?

<wsdl:documentation .... /> ?

</wsdl:output>

<wsdl:fault name="ncname" message="qname"> *

<wsdl:documentation .... /> ?

</wsdl:fault>

</wsdl:operation>

</wsdl:portType>

<wsdl:serviceType name="ncname"> *

<wsdl:portType name="qname"/> +

</wsdl:serviceType>

<wsdl:binding name="ncname" type="qname"> *

<wsdl:documentation .... /> ?

<-- binding details --> *

<wsdl:operation name="ncname"> *

<wsdl:documentation .... /> ?

<-- binding details --> *

<wsdl:input> ?

<wsdl:documentation .... /> ?

<-- binding details -->

</wsdl:input>

<wsdl:output> ?

<wsdl:documentation .... /> ?

<-- binding details --> *

</wsdl:output>