Written by
Tom Donohue
Updated: 20 December 2024
Comments
If you’re a developer who’s working with web services, you might one day be asked to integrate using something called WSDL. What is it, and how do you use it? Here’s what you need to know about WSDL web services and SOAP.
In this guide we’re going to cover:
What is WSDL, really?
What is the structure of a WSDL file, and what do the elements mean?
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.
It defines the operations in a web service, the messages used by each operation, and what each message should look like.
A WSDL file describes a web service’s operations, data types, protocols and endpoints
A valid WSDL file contains all the information you need to send a request to a web service.
You can think of a WSDL file as an instruction manual for interacting with a web service.
It defines the rules and format for the communication between your application and the web service you’re trying to talk to.
A WSDL file is usually given 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 servicesThe WSDL language doesn’t enforce any particular way of accessing a web service.
Instead, when you describe a web service in WSDL, you define one or more bindings.
A binding specifies the details of how the web service will be accessed, and how the messages will be exchanged between the service provider and its consumers.
BindingsThe 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 servicesAlthough WSDL can describe web services with various different bindings, it was never designed to work with REST services.
REST is a very different architectural style of web services, and it isn’t really compatible with WSDL.
Is WSDL still used anymore? 🤠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 most technologies, it got superseded by new technologies.
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”, “SeCustomer”), 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 fileA WSDL document is written in XML and contains the following elements:
Element What it does Defines the data types (XML elements) that are used by the web service. Defines the messages that can be exchanged with the web service. Each contains a . Defines each operation in the web service, and the messages associated with each operation. Defines exactly how each operation will take place over the network (we use SOAP, in the example below). Defines the physical location of the service (e.g. its endpoint). 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 codeYou 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 Ja, you can use any library which implements Ja’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 toolYou 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 fileHere 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
A note on binding stylesThere are several different ways to bind a WSDL to a SOAP message.
This example uses the “document-literal wrapped” binding pattern.
‘Document-literal wrapped’ is the most widely accepted format, although it is a little complex to write from scratch, which is why some people find it helpful to see a finished example.
What is a 'document-literal wrapped' style WSDL?‘Document-literal wrapped’ describes a WSDL where the request and response parameters for an operation are “wrapped” inside all-encompassing request and response elements, which are defined in the WSDL’s types section. 1
Additionally, in document-literal wrapped style, the request element has the same name as the SOAP operation. For example, an operation GetBook will be invoked using an element called GetBook.
The example: BookService.wsdlThis WSDL is just for learning purposes. It doesn’t point to a “real” web service. If you want to use this WSDL in an application, you can import it into soapUI and create a mock service.
Definition for a web service called BookService, which can be used to add or retrieve books from a collection. See this example in actionIf you want to see this WSDL used in an Apache Camel (Ja) application, then check out the file here:
See this example in a Camel app on GitHub
Wrapping upWe’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!
Akram, Asif, Rob Allan, and Did Meredith. “Best practices in web service style, data binding and validation for use in data-centric scientific applications.” e-Science All Hands Meeting. 2006. https://epubs.stfc.ac.uk/manifestation/1133/621.pdf ↩
By Tom Donohue, Editor | Twitter | LinkedIn
Tom is the founder of Tutorial Works. He’s an engineer and open source advocate. He uses the blog as a vehicle for sharing tutorials, writing about technology and talking about himself in the third person. His very first computer was an Acorn Electron.
Thanks for reading. Let's stay in touch.It took us this long to find each other. So before you close your browser and forget all about this article, shall we stay in touch?
Join our free members' newsletter. We'll email you our latest tutorials and guides, so you can read at your leisure! 🏖 (No spam, unsubscribe whenever you want.)
Thank you!We've sent you an email. Please check your email, and click the link inside to confirm your subscription.
Got some thoughts on what you've just read? Want to know what other people think? Or is there anything technically wrong with the article? (We'd love to know so that we can correct it!) Join the conversation and lee a comment.
Comments are moderated.
Want more? Read these articles next...You've found the end of another article! Keep on learning by checking out one of these articles:
Using environment variables in shell scripts: Tutorial: Environment variables are one of those Linux things that, once they click, you’ll be using them everywhere.
Unit vs integration testing: What's the difference?: We demystify the difference between unit and integration testing, and explain why both are important
7 power features of the Linux shell you really need to know: Here are some power features that you can use to get things done quicker and easier
Men POM template - an example: Try this example Men project file to bootstrap a new Ja project.
Secure your Linux services with this guide to systemd's little-known security options: Creating a systemd service? Use this handy guide to make it more secure.