Defining the Web Service with WSDL
by Thomas Erl

Web services need to be defined in a consistent manner so that they can be discovered by and interfaced with other services and applications. The Web Services Description Language (WSDL) is a W3C specification providing the foremost language for the description of Web service interfaces.

A WSDL service description describes the point of contact for a service, also known as the service endpoint or just endpoint. It establishes the physical location of the service and provides a formal definition of the endpoint interface so that programs wishing to communicate with the service know exactly how to structure the required request messages.

Let’s take a closer look at how the service description document itself is organized. The WSDL service description (also known as WSDL service definition or just WSDL definition) can be separated into two parts:

• abstract description

• concrete description

The following diagram shows how these individual descriptions comprise a WSDL definition. Note the logical hierarchy established within the parts of the abstract definition. We will explain each of these parts shortly.



The Abstract Description

An abstract description establishes the interface characteristics of the Web service without any reference to the technology used to host or enable a Web service to transmit messages. By separating this information, the integrity of the service description can be preserved regardless of what changes might occur to the underlying technology platform. The three main parts that comprise an abstract description are the portType, operation, and message.

The parent portType section of an abstract description provides a high-level view of the service interface, by sorting the messages a service can process into groups of functions known as operations. Each operation represents a specific action performed by the service. A service operation is comparable to a public method used by components in traditional distributed applications.

Much like component methods, operations also have input and output parameters. Because Web services rely exclusively on messaging-based communication, parameters are represented as messages. Therefore, an operation consists of a set of input and output messages.

(Note that the transmission sequence of these messages can be governed by a predetermined message exchange pattern that is also associated with the operation. Also note that term “portType” is being renamed to “interface” in version 2.0 of the WSDL specification.)


The Concrete Description

In order for a Web service to be able to execute any of its logic it needs for its abstract interface definition to be connected to some real, implemented technology. Because the execution of service application logic always involves communication, the abstract Web service interface needs to be connected to a physical transport protocol. This connection is defined in the concrete description portion of the WSDL file, which consists of three related parts: binding, port, and service.

A WSDL description's binding describes the requirements for a service to establish physical connections or for connections to be established with the service. In other words, a binding represents one possible transport technology the service can use to communicate. SOAP is the most common form of binding, but others are also supported. A binding can apply to an entire interface or just a specific operation.

Related to the binding is the port, which represents the physical address at which a service can be accessed with a specific protocol. This piece of physical implementation data exists separately to allow location information to be maintained independently from other aspects of the concrete description. Within the WSDL language, the term service is used to refer to a group of related endpoints.

(Note that the term “port” is being renamed to “endpoint” in version 2.0 of the WSDL specification. The WSDL endpoint should not be confused with the general term “endpoint” used to reference the point of contact for a Web service. Though related, the term “endpoint” is used in a much broader sense than the WSDL endpoint which refers to a language element that only represents the physical address of the service.)

Each of the parts we just described (of both abstract and concrete descriptions) relates to corresponding elements that are defined in the WSDL specification, as shown in the following figure:


To acquire a fundamental understanding of WSDL, you should be familiar with these primary elements. Let's therefore describe each in more detail.


The definitions Element

This is the root or parent element of every WSDL document. It houses all other parts of the service definition, and is also the location in which the many namespaces used within WSDL documents are established.

<definitions
   name="Employee"
   targetNamespace="http://www.xmltc.com/tls/employee/wsdl/"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:act="http://www.xmltc.com/tls/employee/schema/accounting/"
   xmlns:hr="http://www.xmltc.com/tls/employee/schema/hr/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.xmltc.com/tls/employee/wsdl/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   ...
</definition>

In the above example, the service definition is started with a definitions element that contains a series of attributes in which the service is assigned the name of “Employee”, and in which a number of namespaces are declared.

For example, the xmlns attribute establishes the standard value of http://schemas.xmlsoap.org/wsdl/ as the default namespace. This means that all of the elements that belong to the WSDL language do not need prefixes (or qualifiers) to associate them with the WSDL specification.

By defining the xmlns:xsd namespace declaration, all elements within the WSDL that belong to the XML Schema Definition Language need to be prefixed with the xsd: qualifier. Also, note the use of the xmlns:act and xmlns:hr namespace declarations. These are used to distinguish between two separate schemas that are imported into the types construct.

The xmlns:soap namespace declaration establishes the soap: prefix used by elements introduced later in the bindings construct, where the WSDL definition associates its abstract operations to concrete SOAP bindings.


The types Element

The types construct is where XSD schema content is placed. This part of the WSDL can consist of actual XSD schema markup (an entire schema construct containing type definitions), or it can contain import elements that reference external schema definitions (or it can contain both embedded and imported XSD types).

As explained in the next diagram, the types established in this part of the WSDL definition are used to represent the XML content of message bodies. The message element (explained later) references these types and associates them with messages.


The SOAP message body contains XML content that can represent anything from simple parameter data to complex business documents. This content can be formally defined through types provided by the WSDL types area. Therefore, XSD schema complexType elements are commonly provided here, as they consist of groups of related types that can represent entire message body structures.

In the following example, an entire schema construct is embedded within the WSDL types construct.

<types>
  <schema xmlns="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.xmltc.com/railco/transform/schema/">
    <complexType name="ReturnCodeType">
      <sequence>
        <element name="Code" type="xsd:integer"/>
        <element name="Message" type="xsd:string"/>
      </sequence>
    </complexType>
  </schema>
</types>

Use of the types construct is common in WSDL definitions with substantial content. However, it is not a required element. Native XSD schema types can be referenced directly within the message element, as explained next.


The message and part Elements

For every message a service is designed to receive or transmit, a message construct must be added. This element assigns the message a name and contains one or more part child elements that are each assigned a type. message elements are later associated to operation elements to establish the input and output messages of the operation.

part elements use the type or element attributes to identify the data type of the message part. The type attribute can be assigned a simple or complex type, and is generally used for RPC-style messages. part elements in document-style messages typically rely on the element attribute, which can reference an XSD element element. The name attribute is used to uniquely identify part elements within a message construct.

In the example below, we define request and response messages with two separate message constructs. Each message contains a part element that is assigned a pre-defined XSD element using the element attribute.

<message name="getEmployeeWeeklyHoursRequestMessage">
  <part name="RequestParameter" element="act:EmployeeHoursRequestType"/>
</message>
<message name="getEmployeeWeeklyHoursResponseMessage">
  <part name="ResponseParameter" element="act:EmployeeHoursResponseType"/>
</message>

In the next example the part element is simply assigned a native XSD schema data type using the type attribute.

<message name="getID">
  <part type="xsd:integer"/>
</message>

If all messages in a WSDL definition are assigned native (simple) XSD types, then a separate types construct is generally not required.


The portType, interface, and operation Elements

Service operations are defined within the portType area of the WSDL definition. Hence, portType constructs simply represent collections of operations. Individual operations are defined using the aptly named operation element.

<portType name="EmployeeInterface">
  <operation name="GetWeeklyHoursLimit">
    ...
  </operation>
  <operation name="UpdateHistory">
    ...
  </operation>
</portType>

(Note that the portType element is defined in version 1.1 of the Web Services Description Language. Version 2.0 of this specification changes the name of this element from portType to interface. The examples provided here are based on WSDL 1.1, and therefore continue to use the portType element.)


The input and output Elements (when used with operation)

Each operation construct contains input and/or output child elements that represent the request and response messages the operation is capable of processing.

In the example below, each operation has one input and one output message. The respective input and output elements are assigned messages defined in the message constructs (explained in the previous section) via their message attributes.

<operation name="GetWeeklyHoursLimit">
  <input message="tns:getWeeklyHoursRequestMessage"/>
  <output message="tns:getWeeklyHoursResponseMessage"/>
</operation>
<operation name="UpdateHistory">
  <input message="tns:updateHistoryRequestMessage"/>
  <output message="tns:updateHistoryResponseMessage"/>
</operation>

The presence of input and output elements, and the sequence in which they are displayed generally establish one of several predefined message exchange patterns (MEPs) for the operation. For instance, the two operations defined in the previous example represent the request-response MEP.

Placing a single input element within the operation construct expresses the one-way MEP, as shown in the example below.

<operation name="Submit">
  <input message="tns:receiveSubmitMessage"/>
</operation>

(Note that it may seem confusing to associate request-and-response with a sequence of input and then output messages, because there is a tendency to think that a request requires the service to initiate communication. The reason this makes sense in the Web services world, is because WSDL definitions express an interface from the perspective of the service provider. So, the request-response MEP, to a WSDL, means that a requestor will send it - the service provider - a request as input, to which it - the service provider - will reply with a response as output.)


The binding Element

So far, all of the elements we’ve described belong to the abstract service definition. On their own, they complete the description of a service interface, but without referencing any means of messaging communication technology.

The binding element begins the concrete portion of the service definition, in order to assign a communications protocol that can be used to access and interact with the WSDL.

Upon first glance of the example below, the binding element appears similar in structure to the portType element. As with portType, the binding construct contains one or more operation elements.

However, you’ll notice the additional soap:binding and soap:operation elements interspersed within the construct syntax. These are what establish the SOAP protocol as the manner in which this WSDL can be communicated with.

<binding name="EmployeeBinding" type="tns:EmployeeInterface">
  <soap:binding style="document"
    transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="GetWeeklyHoursLimit">
      <soap:operation soapAction="..."/>
      ...
    </operation>
    <operation name="UpdateHistory">
      <soap:operation soapAction="..."/>
      ...
    </operation>
</binding>

Further, the style attribute of the soap:binding element defines whether the SOAP messages used to support an operation are to be formatted as document or RPC-style messages.

The value of "document" allows the SOAP message body to contain a fully definable XML document structure. Assigning a value of "rpc" to the style attribute requires compliance to a body structure defined within the SOAP specification, which primarily forces the root element of the body to be named after the operation name.


The input and output Elements (when used with binding)

Each operation element within a binding construct mirrors the input and output message child elements defined in the abstract definition.

Within a binding construct, however, the input and output elements do not reference the message elements again. Instead, they contain protocol details that establish how the messages are going to be processed and interpreted by the chosen communication technology.

In our next example, the service interface has been bound to the SOAP protocol.

<operation name="GetWeeklyHoursLimit">
  <soap:operation soapAction="..."/>
  <input>
    <soap:body use="literal"/>
  </input>
  <output>
    <soap:body use="literal"/>
  </output>
</operation>
<operation name="UpdateHistory">
  <soap:operation soapAction="..."/>
    <input>
  <soap:body use="literal"/>
  </input>
  <output>
    <soap:body use="literal"/>
  </output>
</operation>

This introduces the soap:body element from the SOAP language that defines the data type system to be used by SOAP processors, via the use attribute. The use attribute can be set to "encoding" or "literal".

(Note that how the style and use attributes affect the processing of messages within a service-oriented architecture is discussed in the WSDL and SOA section in Chapter 14 of "Service-Oriented Architecture: Concepts, Technology, and Design".)


The service, port, and endpoint Elements

The service element simply provides a physical address at which the service can be accessed. It hosts the port element that contains the location information.

<service name="EmployeeService">
  <port binding="tns:EmployeeBinding" name="EmployeePort">
    <soap:address location="http://www.xmltc.com/tls/employee/"/>
  </port>
</service>

Because we are binding to the SOAP protocol, the port element contains a child soap:address element with the physical address information.

(Note that the port element is replaced with the endpoint element in version 2.0 of the WSDL specification.)


The import Element

The WSDL language supports a similar form of modularity as XSD schemas do, in that it provides its own import element that can be used to import one WSDL into another.

The example below shows an import element referencing a schema document.

<import namespace="http://www.xmltc.com/tls/schemas/" location="http://www.xmltc.com/tls/schemas/employee.xsd"/>

For more information about how the design of WSDL service definitions is affected when incorporating Web services within service-oriented architectures, see Service-Oriented Architecture: Concepts, Technology, and Design.

SOA Design Patterns by Thomas Erl
Foreword by Grady Booch
With contributions from David Chappell, Jason Hogg, Anish Karmarkar, Mark Little, David Orchard, Satadru Roy, Thomas Rischbeck, Arnaud Simon, Clemens Utschig, Dennis Wisnosky, and others.
Web Service Contract Design & Versioning for SOA by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley
SOA Principles of Service Design by Thomas Erl
Service-Oriented Architecture: A Field Guide to Integrating XML and Web Services by Thomas Erl
Service-Oriented Infrastructure:On-Premise and in the Cloud by Raj Balasubramanian, Benjamin Carlyle, Thomas Erl, Cesare Pautasso
Next Generation SOA:A Real-World Guide to Modern Service-Oriented Computing by Pethuru Cheliah, Thomas Erl, Clive Gee, Robert Laird, Berthold Maier, Hajo Normann, Leo Shuster, Bernd Trops, Clemens Utschig, Torsten Winterberg
SOA with .NET & Windows Azure: Realizing Service-Orientation with the Microsoft Platform by David Chou, John deVadoss, Thomas Erl, Nitin Gandhi, Hanu Kommalapati, Brian Loesgen, Christoph Schittko, Herbjorn Wilhelmsen, Mickey Williams
SOA Governance:
Governing Shared Services On-Premise & in the Cloud
by Stephen Bennett, Thomas Erl, Clive Gee, Anne Thomas Manes, Robert Schneider, Leo Shuster, Andre Tost, Chris Venable
SOA with Java by Raj Balasubramanian, David Chou, Thomas Erl, Thomas Plunkett, Satadru Roy, Philip Thomas, Andre Tost
Modern SOA Methodology: Methods for Applying Service-Orientation On-Premise & in the Cloud by Raj Balasubramanian, David Chou, Thomas Erl, Thomas Plunkett, Satadru Roy, Philip Thomas, Andre Tost
Cloud Computing: Concepts, Technology & Architecture by Thomas Erl, Zaigham Mahmood, Ricardo Puttini
Cloud Computing Design Patterns by Thomas Erl, Amin Naserpour

For more information about these books, visit: www.servicetechbooks.com


Arcitura Education Inc.
Arcitura Education Inc. is a leading global provider of progressive, vendor-neutral training and certification programs, providing industry-recognized certification programs for a range of certifications.
For more information:
www.arcitura.com
SOA Certified Professional (SOACP)
The books in this series are part of the official curriculum for the SOA Certified Professional program.
For more information:
www.soaschool.com
Cloud Certified Professional (CCP)
The books in this series are part of the official curriculum for the Cloud Certified Professional program.
For more information:
www.cloudschool.com
Big Data Science Certified Professional (BDSCP)
The books in this series are part of the official curriculum for the Big Data Science Certified Professional program.
For more information:
www.bigdatascienceschool.com/