The simple guide to WSDL (with an example)

You hear a faint rumour, you hurry back to your desk and then an email pops into your inbox. It’s a WSDL file. You realise that you’re going to need to learn about SOAP web services. If this is you right now, then here’s everything you need to know about SOAP and WSDL.

At first glance, WSDL files can seem very quirky and difficult to understand.

So in this guide we’re going to cover:

• What is WSDL, really?

• The structure of a WSDL file (how to understand all the elements in it)

• A proper, valid example WSDL you can use

What is a WSDL file?

Let’s start with the basics! What is WSDL?

Web Services Description Language (WSDL) is an XML-based language for describing web services.

A WSDL file is written in XML and defines the operations in a web service, the messages used by each operation, and what the messages look like.

A valid WSDL file contains all the information you need to send a request to a web service. Think of it like a “blueprint” or an instruction manual for interacting with a web service.

The WSDL file is usually given out to consumers of a web service, either directly as a download from the service itself, or distributed separately.

WSDL works with different types of web services

WSDL doesn’t insist that a service must have a certain message format, or must be accessed using a certain network protocol.

Instead, in WSDL you choose a binding. This is where you give a concrete definition of how the service will be accessed, and what data format it will use.

Bindings

The WSDL specification describes these 3 bindings:

• SOAP binding (this is undeniably the most common way to use WSDL)

• HTTP GET and POST binding

• MIME binding

But it’s not for REST services

Although WSDL can describe web services with a few different bindings, it was never designed to work with REST services. REST is a very different architectural style of web services, and its philosophy isn’t really compatible with WSDL.

The ol’ WSDL days 🤠

Where did WSDL go? Why it still around?

People were really excited about WSDL in the early 2000s, when companies began to use web services to connect their internal systems. But, just like with most technologies, it got superseded. Lightweight alternatives like REST or JSON-based services arrived. Many teams eventually said goodbye to XML-based web services.

These days, people don’t often choose WSDL for new systems, but many legacy systems still depend on it, so you’ll see it in use inside many huge companies.

How is WSDL related to SOAP?

You’ve probably seen the term WSDL alongside SOAP. So how are the two terms related?

SOAP is a standard for exchanging messages with a server, which is designed to work like calling a method or procedure in a computer program (except it takes place over a network). SOAP sits on top of an existing transport, like HTTP.

The SOAP standard defines things that are common to lots of services:

• The structure of messages – an Envelope containing a Header and a Body

• A way to return fault or error messages from the service

• A way to enhance messages with other features, like message encryption

By contrast, WSDL is a language that allows us to define:

• The operations you can call on a service

• The messages that you can exchange with a service

So while WSDL defines the operations and messages for a particular web service (e.g. “GetBook”, “SaveCustomer”), SOAP defines the concrete format for exchanging those messages with a server.

WSDL is most commonly seen to describe SOAP web services.

Structure of a WSDL file

A WSDL document is written in XML and contains the following elements:

How do you use a WSDL file?

A WSDL file is designed for computers to understand. It’s a contract, which can be understood by machines.

It’s basically a manual or recipe that describes a web service.

You can use the information in a WSDL file to:

• Call the remote web service which the WSDL describes – either by writing some code or using a testing tool

• Write your own web service, which implements the definitions in the WSDL

• Create sample request or response messages for the service

Using a WSDL in your code

You can use a WSDL to create code that calls a web service.

But usually, you don’t write code to read and parse a WSDL file yourself. Instead, you use a library for your programming language, like one of these libraries:

• In Java, you can use any library which implements Java’s JAX-WS standard, such as Apache CXF. CXF can read WSDL files and interact with SOAP services. Or, if you don’t want to configure CXF yourself, you can use an integration framework like Apache Camel, which indirectly uses CXF.

• In Python, you can use Zeep, which is a library that can parse a WSDL file, and generate code so you can call the remote web service.

Using a WSDL in a testing tool

You can also use a desktop program to parse a WSDL and interact with the web service it describes.

You can use use one of these tools:

• soapUI, an open source desktop application for testing web services

• Postman, another desktop application for testing web services

• Boomerang, an extension for Google Chrome for testing SOAP services

Next, let’s take a look at an example WSDL file.

Example WSDL file

Here is an example WSDL file which describes an imaginary web service called BookService.

The service exposes three synchronous (input/output) operations:

• GetBook - gets information about a single book from the collection

• AddBook - adds a book to the collection

• GetAllBooks - retrieves all books from the collection

The example: BookService.wsdl

Feel free to use this example WSDL file in your own learning or testing, but it comes without any warranty or licence.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://www.cleverbuilder.com/BookService/"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  name="BookService"
                  targetNamespace="http://www.cleverbuilder.com/BookService/">
  <wsdl:documentation>Definition for a web service called BookService,
    which can be used to add or retrieve books from a collection.
  </wsdl:documentation>

  <!--
      The `types` element defines the data types (XML elements)
      that are used by the web service.
   -->
  <wsdl:types>
    <xsd:schema targetNamespace="http://www.cleverbuilder.com/BookService/">
      <xsd:element name="Book">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="ID" type="xsd:string" minOccurs="0"/>
            <xsd:element name="Title" type="xsd:string"/>
            <xsd:element name="Author" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="Books">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="unbounded"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      <xsd:element name="GetBook">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="ID" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="GetBookResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      <xsd:element name="AddBook">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="1" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="AddBookResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="GetAllBooks">
        <xsd:complexType/>
      </xsd:element>
      <xsd:element name="GetAllBooksResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="unbounded"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>


  <!--
      A wsdl `message` element is used to define a message
      exchanged between a web service, consisting of zero
      or more `part`s.
   -->

  <wsdl:message name="GetBookRequest">
    <wsdl:part element="tns:GetBook" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="GetBookResponse">
    <wsdl:part element="tns:GetBookResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="AddBookRequest">
    <wsdl:part name="parameters" element="tns:AddBook"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="AddBookResponse">
    <wsdl:part name="parameters" element="tns:AddBookResponse"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="GetAllBooksRequest">
    <wsdl:part name="parameters" element="tns:GetAllBooks"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="GetAllBooksResponse">
    <wsdl:part name="parameters" element="tns:GetAllBooksResponse"></wsdl:part>
  </wsdl:message>

  <!--
      A WSDL `portType` is used to combine multiple `message`s
      (e.g. input, output) into a single operation.

      Here we define three synchronous (input/output) operations
      and the `message`s that must be used for each.
   -->
  <wsdl:portType name="BookService">
    <wsdl:operation name="GetBook">
      <wsdl:input message="tns:GetBookRequest"/>
      <wsdl:output message="tns:GetBookResponse"/>
    </wsdl:operation>
    <wsdl:operation name="AddBook">
      <wsdl:input message="tns:AddBookRequest"></wsdl:input>
      <wsdl:output message="tns:AddBookResponse"></wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="GetAllBooks">
      <wsdl:input message="tns:GetAllBooksRequest"></wsdl:input>
      <wsdl:output message="tns:GetAllBooksResponse"></wsdl:output>
    </wsdl:operation>
  </wsdl:portType>

  <!--
      The `binding` element defines exactly how each
      `operation` will take place over the network.
      In this case, we are using SOAP.
   -->
  <wsdl:binding name="BookServiceSOAP" type="tns:BookService">
    <soap:binding style="document"
                  transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="GetBook">
      <soap:operation
              soapAction="http://www.cleverbuilder.com/BookService/GetBook"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="AddBook">
      <soap:operation
              soapAction="http://www.cleverbuilder.com/BookService/AddBook"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="GetAllBooks">
      <soap:operation
              soapAction="http://www.cleverbuilder.com/BookService/GetAllBooks"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

  <!--
      The `service` element finally says where the service
      can be accessed from - in other words, its endpoint.
   -->
  <wsdl:service name="BookService">
    <wsdl:port binding="tns:BookServiceSOAP" name="BookServiceSOAP">
      <soap:address location="http://www.example.org/BookService"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

See this example in action

If you want to see this WSDL used in an Apache Camel (Java) application, then check out the file here:

See this example in a Camel app on GitHub

Wrapping up

We’ve learned about WSDL files and how they’re related to SOAP.

WSDL is a language for describing web or network services. SOAP is a message format for exchanging messages with a server.

Try using the example WSDL file above in your own learning projects, or plug it into a testing tool like soapUI.

Good luck!