PetstoreAPI WSDL Protocol Guide - Modern PetstoreAPI Docs

Overview

WSDL Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl Protocol: SOAP (Simple Object Access Protocol) WSDL Version: WSDL 1.1 / WSDL 2.0 compatible Binding: SOAP 1.1 over HTTP WSDL is an XML-based interface description language for describing the functionality offered by a SOAP web service. It provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns.

What is WSDL?

WSDL (Web Services Description Language) is an XML format for describing network services as a set of endpoints operating on messages. It was designed for SOAP-based web services and provides a formal contract for service integration.

Key Features

✅ Service Contract: Formal definition of service operations
✅ Type System: Uses XML Schema for data types
✅ Protocol Binding: Supports SOAP, HTTP, and other protocols
✅ Enterprise Integration: Standard for enterprise service buses (ESB)
✅ Tool Support: Wide tooling support across platforms
✅ Strong Typing: Strict schema validation

When to Use WSDL/SOAP

WSDL is particularly useful when:

Integrating with enterprise systems (SAP, Oracle, Microsoft)
Requiring formal service contracts (SLA agreements)
Working with .NET or Java enterprise frameworks
Needing built-in security (WS-Security)
Supporting transactional operations (WS-AtomicTransaction)
Implementing complex messaging patterns

WSDL Structure

A WSDL document consists of these main elements:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="PetstoreService"
             targetNamespace="http://petstoreapi.com/wsdl"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://petstoreapi.com/wsdl"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <!-- Types: Data type definitions -->
  <types>
    <xsd:schema targetNamespace="http://petstoreapi.com/wsdl">
      <!-- Schema definitions -->
    </xsd:schema>
  </types>

  <!-- Messages: Input/output message definitions -->
  <message name="GetPetRequest">
    <part name="id" type="xsd:string"/>
  </message>
  <message name="GetPetResponse">
    <part name="pet" type="tns:Pet"/>
  </message>

  <!-- Port Type: Abstract service operations -->
  <portType name="PetstorePortType">
    <operation name="getPet">
      <input message="tns:GetPetRequest"/>
      <output message="tns:GetPetResponse"/>
    </operation>
  </portType>

  <!-- Binding: Protocol and data format -->
  <binding name="PetstoreSoapBinding" type="tns:PetstorePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getPet">
      <soap:operation soapAction="http://petstoreapi.com/getPet"/>
      <input><soap:body use="literal"/></input>
      <output><soap:body use="literal"/></output>
    </operation>
  </binding>

  <!-- Service: Endpoint location -->
  <service name="PetstoreService">
    <port name="PetstoreSoapPort" binding="tns:PetstoreSoapBinding">
      <soap:address location="https://api.petstoreapi.com/v1/soap"/>
    </port>
  </service>

</definitions>

Understanding WSDL Elements

Types

Defines data structures using XML Schema:

<types>
  <xsd:schema targetNamespace="http://petstoreapi.com/wsdl">

    <!-- Pet complex type -->
    <xsd:complexType name="Pet">
      <xsd:sequence>
        <xsd:element name="id" type="xsd:string"/>
        <xsd:element name="name" type="xsd:string"/>
        <xsd:element name="species" type="tns:PetSpecies"/>
        <xsd:element name="ageMonths" type="xsd:int"/>
        <xsd:element name="status" type="tns:PetStatus"/>
      </xsd:sequence>
    </xsd:complexType>

    <!-- Enum for species -->
    <xsd:simpleType name="PetSpecies">
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="DOG"/>
        <xsd:enumeration value="CAT"/>
        <xsd:enumeration value="RABBIT"/>
        <xsd:enumeration value="BIRD"/>
        <xsd:enumeration value="REPTILE"/>
        <xsd:enumeration value="OTHER"/>
      </xsd:restriction>
    </xsd:simpleType>

  </xsd:schema>
</types>

Messages

Defines input and output messages for operations:

<!-- Request messages -->
<message name="GetPetRequest">
  <part name="id" type="xsd:string"/>
</message>

<message name="CreatePetRequest">
  <part name="pet" type="tns:Pet"/>
</message>

<!-- Response messages -->
<message name="GetPetResponse">
  <part name="pet" type="tns:Pet"/>
</message>

<message name="CreatePetResponse">
  <part name="pet" type="tns:Pet"/>
</message>

<!-- Fault messages -->
<message name="PetNotFoundFault">
  <part name="fault" type="tns:ErrorDetail"/>
</message>

Port Type

Defines abstract operations:

<portType name="PetstorePortType">

  <operation name="getPet">
    <input message="tns:GetPetRequest"/>
    <output message="tns:GetPetResponse"/>
    <fault name="notFound" message="tns:PetNotFoundFault"/>
  </operation>

  <operation name="createPet">
    <input message="tns:CreatePetRequest"/>
    <output message="tns:CreatePetResponse"/>
    <fault name="validationError" message="tns:ValidationFault"/>
  </operation>

  <operation name="updatePet">
    <input message="tns:UpdatePetRequest"/>
    <output message="tns:UpdatePetResponse"/>
  </operation>

  <operation name="deletePet">
    <input message="tns:DeletePetRequest"/>
    <output message="tns:DeletePetResponse"/>
  </operation>

</portType>

Binding

Specifies concrete protocol and data format:

<binding name="PetstoreSoapBinding" type="tns:PetstorePortType">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

  <operation name="getPet">
    <soap:operation soapAction="http://petstoreapi.com/getPet"/>
    <input><soap:body use="literal"/></input>
    <output><soap:body use="literal"/></output>
    <fault name="notFound"><soap:fault name="notFound" use="literal"/></fault>
  </operation>

</binding>

Service

Defines endpoint location:

<service name="PetstoreService">
  <documentation>Modern Petstore SOAP Web Service</documentation>
  <port name="PetstoreSoapPort" binding="tns:PetstoreSoapBinding">
    <soap:address location="https://api.petstoreapi.com/v1/soap"/>
  </port>
</service>

Using SOAP Services

SOAP Request Format

SOAP messages are XML envelopes containing headers and body:

POST /v1/soap HTTP/1.1
Host: api.petstoreapi.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://petstoreapi.com/getPet"

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://petstoreapi.com/wsdl">
  <soap:Header>
    <!-- Optional headers (security, transactions, etc.) -->
  </soap:Header>
  <soap:Body>
    <tns:GetPetRequest>
      <id>pet_fYrZzCW9E1WIOyGw</id>
    </tns:GetPetRequest>
  </soap:Body>
</soap:Envelope>

SOAP Response Format

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://petstoreapi.com/wsdl">
  <soap:Body>
    <tns:GetPetResponse>
      <pet>
        <id>pet_fYrZzCW9E1WIOyGw</id>
        <name>Buddy</name>
        <species>DOG</species>
        <breed>Golden Retriever</breed>
        <ageMonths>24</ageMonths>
        <status>AVAILABLE</status>
      </pet>
    </tns:GetPetResponse>
  </soap:Body>
</soap:Envelope>

SOAP Fault (Error) Format

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Pet not found</faultstring>
      <detail>
        <tns:PetNotFoundFault>
          <code>NOT_FOUND</code>
          <message>Pet with ID 'invalid_id' does not exist</message>
        </tns:PetNotFoundFault>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Client Code Examples

Java (JAX-WS)

import javax.xml.ws.Service;
import javax.xml.namespace.QName;
import java.net.URL;

// Load WSDL
URL wsdlLocation = new URL("https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl");
QName serviceName = new QName("http://petstoreapi.com/wsdl", "PetstoreService");

Service service = Service.create(wsdlLocation, serviceName);
PetstorePortType port = service.getPort(PetstorePortType.class);

// Call operations
Pet pet = port.getPet("pet_fYrZzCW9E1WIOyGw");
System.out.println("Found: " + pet.getName());

// Create a new pet
Pet newPet = new Pet();
newPet.setName("Buddy");
newPet.setSpecies(PetSpecies.DOG);
newPet.setAgeMonths(24);

Pet created = port.createPet(newPet);
System.out.println("Created pet with ID: " + created.getId());

C# (.NET)

using System;
using System.ServiceModel;

// Add service reference to WSDL in Visual Studio
// or use svcutil.exe to generate proxy classes

var client = new PetstoreServiceClient();

try
{
    // Get a pet
    var pet = await client.GetPetAsync("pet_fYrZzCW9E1WIOyGw");
    Console.WriteLine($"Found: {pet.Name}");

    // Create a new pet
    var newPet = new Pet
    {
        Name = "Buddy",
        Species = PetSpecies.DOG,
        AgeMonths = 24,
        Status = PetStatus.AVAILABLE
    };

    var created = await client.CreatePetAsync(newPet);
    Console.WriteLine($"Created pet with ID: {created.Id}");
}
catch (FaultException<PetNotFoundFault> ex)
{
    Console.WriteLine($"Error: {ex.Detail.Message}");
}
finally
{
    client.Close();
}

Python (Zeep)

from zeep import Client
from zeep.exceptions import Fault

# Load WSDL
client = Client('https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl')

try:
    # Get a pet
    pet = client.service.getPet(id='pet_fYrZzCW9E1WIOyGw')
    print(f"Found: {pet['name']}")

    # Create a new pet
    new_pet = {
        'name': 'Buddy',
        'species': 'DOG',
        'breed': 'Golden Retriever',
        'ageMonths': 24,
        'status': 'AVAILABLE'
    }

    created = client.service.createPet(pet=new_pet)
    print(f"Created pet with ID: {created['id']}")

except Fault as fault:
    print(f"SOAP Fault: {fault.message}")

PHP (SoapClient)

<?php

$wsdl = 'https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl';
$client = new SoapClient($wsdl);

try {
    // Get a pet
    $response = $client->getPet(['id' => 'pet_fYrZzCW9E1WIOyGw']);
    echo "Found: " . $response->pet->name . "\n";

    // Create a new pet
    $newPet = [
        'name' => 'Buddy',
        'species' => 'DOG',
        'breed' => 'Golden Retriever',
        'ageMonths' => 24,
        'status' => 'AVAILABLE'
    ];

    $created = $client->createPet(['pet' => $newPet]);
    echo "Created pet with ID: " . $created->pet->id . "\n";

} catch (SoapFault $fault) {
    echo "SOAP Fault: " . $fault->getMessage() . "\n";
}
?>

Code Generation

Generate Java Client

# Using wsimport (JDK built-in)
wsimport -keep -p com.example.petstore https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl

# Using Apache CXF wsdl2java
wsdl2java -p com.example.petstore -d src/main/java https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl

Generate C# Client

# Using svcutil (.NET Framework)
svcutil https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl /out:PetstoreClient.cs

# Using dotnet-svcutil (.NET Core)
dotnet tool install --global dotnet-svcutil
dotnet-svcutil https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl -o PetstoreClient.cs

Generate Python Client

# Install zeep
pip install zeep

# Zeep doesn't require code generation - it dynamically parses WSDL
# Optionally generate stubs for IDE support
python -m zeep https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl

Security (WS-Security)

SOAP services support WS-Security for authentication and encryption:

Username Token Authentication

<soap:Header>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
      <wsse:Username>john.doe</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
        hashed_password_here
      </wsse:Password>
      <wsse:Nonce>random_nonce</wsse:Nonce>
      <wsu:Created>2025-01-06T10:00:00Z</wsu:Created>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

Java WS-Security Example

import org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor;
import org.apache.wss4j.dom.WSConstants;
import org.apache.wss4j.dom.handler.WSHandlerConstants;

// Configure WS-Security
Map<String, Object> outProps = new HashMap<>();
outProps.put(WSHandlerConstants.ACTION, WSHandlerConstants.USERNAME_TOKEN);
outProps.put(WSHandlerConstants.USER, "john.doe");
outProps.put(WSHandlerConstants.PASSWORD_TYPE, WSConstants.PW_DIGEST);
outProps.put(WSHandlerConstants.PW_CALLBACK_CLASS, PasswordCallbackHandler.class.getName());

WSS4JOutInterceptor wssOut = new WSS4JOutInterceptor(outProps);
client.getOutInterceptors().add(wssOut);

Best Practices

1. Use Document/Literal Style

✅ RECOMMENDED:
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<soap:body use="literal"/>

❌ AVOID:
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<soap:body use="encoded"/>

Reason: Document/literal style is WS-I compliant and provides better interoperability.

2. Design Coarse-Grained Operations

✅ GOOD: Single operation with complex input
<operation name="createOrder">
  <input message="tns:CreateOrderRequest"/>  <!-- Contains all order details -->
</operation>

❌ BAD: Multiple fine-grained operations
<operation name="setOrderItems"/>
<operation name="setShippingAddress"/>
<operation name="setPaymentInfo"/>

3. Use Meaningful Fault Messages

<message name="ValidationFault">
  <part name="fault" type="tns:ValidationError"/>
</message>

<complexType name="ValidationError">
  <sequence>
    <element name="code" type="xsd:string"/>
    <element name="message" type="xsd:string"/>
    <element name="fields" type="tns:FieldErrors"/>
  </sequence>
</complexType>

4. Version Your Services

Include version in namespace and endpoint:

<definitions targetNamespace="http://petstoreapi.com/wsdl/v1">
  <service name="PetstoreService">
    <port binding="tns:PetstoreSoapBinding">
      <soap:address location="https://api.petstoreapi.com/v1/soap"/>
    </port>
  </service>
</definitions>

SOAP vs REST

Feature	SOAP	REST
Format	XML only	JSON, XML, others
Protocol	SOAP over HTTP/HTTPS	HTTP/HTTPS
Type System	XML Schema (strict)	JSON Schema (flexible)
Standards	WS-* standards (Security, Transactions)	No built-in standards
Stateful	Supports stateful operations	Stateless by design
Caching	Limited	Built-in HTTP caching
Error Handling	SOAP faults	HTTP status codes
Tooling	Enterprise-focused	Developer-friendly
Performance	Heavier (XML overhead)	Lighter (JSON)
Use Case	Enterprise integration	Web and mobile APIs

When to Use SOAP

✅ Choose SOAP when:

Working with enterprise systems (SAP, Oracle, etc.)
Need formal service contracts (WSDL)
Require built-in security (WS-Security)
Supporting transactional operations
Legacy system integration requirements

When to Use REST

✅ Choose REST when:

Building modern web/mobile APIs
Need high performance and scalability
Want simple, human-readable APIs
Targeting multiple platforms
Using microservices architecture

WSDL Tools

Validators

XMLSpy

Full WSDL validation
Schema validation
SOAP message testing

SoapUI

# Download from https://www.soapui.org/
# Import WSDL and test operations

Postman

Import WSDL
Generate SOAP requests
Test SOAP services

Analyzers

WSDL Analyzer

# Parse WSDL structure
wsdlpull https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl

Migration Guide

From SOAP to REST

Modern APIs are moving from SOAP to REST. Here’s the mapping:

SOAP Concept	REST Equivalent
Operation	HTTP Method + Path
Message	Request/Response Body
Port Type	Resource Collection
Binding	Content-Type Header
Fault	HTTP Status + Error Body

Example Conversion:

<!-- SOAP Operation -->
<operation name="getPet">
  <input message="tns:GetPetRequest"/>
  <output message="tns:GetPetResponse"/>
</operation>

# REST Equivalent
GET /pets/{id}
Accept: application/json

# Response
200 OK
Content-Type: application/json

Additional Resources

WSDL Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl
W3C WSDL Spec: https://www.w3.org/TR/wsdl/
SOAP Specification: https://www.w3.org/TR/soap/
WS-Security: http://docs.oasis-open.org/wss/
Related Protocols:

Support

For questions or issues with the WSDL specification:

GitHub Issues: https://github.com/petstoreapi/PetstoreAPI/issues
Documentation: https://docs.petstoreapi.com
API Reference: https://docs.petstoreapi.com

Getting Started

Protocol Guides

​Overview

​What is WSDL?

​Key Features

​When to Use WSDL/SOAP

​WSDL Structure

​Understanding WSDL Elements

​Types

​Messages

​Port Type

​Binding

​Service

​Using SOAP Services

​SOAP Request Format

​SOAP Response Format

​SOAP Fault (Error) Format

​Client Code Examples

​Java (JAX-WS)

​C# (.NET)

​Python (Zeep)

​PHP (SoapClient)

​Code Generation

​Generate Java Client

​Generate C# Client

​Generate Python Client

​Security (WS-Security)

​Username Token Authentication

​Java WS-Security Example

​Best Practices

​1. Use Document/Literal Style

​2. Design Coarse-Grained Operations

​3. Use Meaningful Fault Messages

​4. Version Your Services

​SOAP vs REST

​When to Use SOAP

​When to Use REST

​WSDL Tools

​Validators

​Analyzers

​Migration Guide

​From SOAP to REST

​Additional Resources

​Support