PetstoreAPI WADL Protocol Guide - Modern PetstoreAPI Docs

Overview

WADL Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.wadl Protocol: XML-based description language for HTTP APIs WADL Version: Following the W3C WADL 2009-02 specification WADL is a machine-readable XML format that describes HTTP-based web applications and RESTful web services. It provides a structured way to describe resources, methods, parameters, and representations.

What is WADL?

WADL (Web Application Description Language) is an XML-based file format that provides a machine-readable description of HTTP-based web applications. It was designed to simplify the development and documentation of RESTful web services.

Key Features

✅ Resource-Oriented: Describes REST resources and their hierarchies
✅ Method Definitions: Specifies HTTP methods (GET, POST, PUT, DELETE, etc.)
✅ Parameter Description: Documents path, query, and header parameters
✅ Media Types: Defines request and response representations
✅ Type System: Uses XML Schema types for validation
✅ Tool Generation: Enables automatic client generation

When to Use WADL

WADL is particularly useful when:

Working with Java-based web services
Using tools that consume WADL (like JAX-RS)
Integrating with legacy systems expecting WADL
Generating client code from service descriptions
Documenting RESTful APIs in XML format

WADL Structure

Our WADL specification follows this structure:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://wadl.dev.java.net/2009/02"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <!-- API Documentation -->
  <doc title="Modern Petstore API">
    API description and metadata
  </doc>

  <!-- Resources -->
  <resources base="https://api.petstoreapi.com/v1">

    <!-- Resource Definition -->
    <resource path="/pets/{id}">
      <!-- Path Parameters -->
      <param name="id" style="template" type="xsd:string" required="true">
        <doc>Unique identifier for the pet</doc>
      </param>

      <!-- HTTP Methods -->
      <method name="GET" id="getPet">
        <doc title="Get Pet">Retrieve pet details</doc>
        <response status="200">
          <representation mediaType="application/json" element="Pet" />
        </response>
      </method>
    </resource>

  </resources>
</application>

Downloading the WADL Specification

Direct Download

# Download WADL specification
curl https://api.petstoreapi.com/v1/specs/modern-petstore.wadl -o petstore.wadl

# Validate XML structure
xmllint --noout petstore.wadl

Specification Details

The WADL specification includes:

11 resource paths: All REST API endpoints
18 HTTP methods: Complete CRUD operations
Path parameters: Template-style parameters with validation
Query parameters: Filtering and pagination support
Request bodies: JSON representations with schema references
Response definitions: Status codes and media types
Documentation: Inline descriptions for all elements

Understanding WADL Elements

Application Element

The root element containing the entire API description:

<application xmlns="http://wadl.dev.java.net/2009/02"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <!-- API content -->
</application>

Resources Element

Defines the base URL and contains all resource definitions:

<resources base="https://api.petstoreapi.com/v1">
  <!-- Resource elements -->
</resources>

Resource Element

Represents a REST resource with its path and operations:

<resource path="/pets">
  <!-- Methods -->
</resource>

<resource path="/pets/{id}">
  <param name="id" style="template" type="xsd:string" required="true" />
  <!-- Methods -->
</resource>

Method Element

Describes an HTTP operation on a resource:

<method name="GET" id="getPet">
  <doc title="Get Pet">Retrieve detailed pet information</doc>
  <request>
    <!-- Request parameters and body -->
  </request>
  <response status="200">
    <!-- Response representations -->
  </response>
</method>

Parameter Element

Defines input parameters:

<!-- Path parameter -->
<param name="id" style="template" type="xsd:string" required="true">
  <doc>Unique identifier for the pet</doc>
</param>

<!-- Query parameter -->
<param name="species" style="query" type="xsd:string">
  <doc>Filter by pet species</doc>
</param>

<!-- Array parameter -->
<param name="status" style="query" type="xsd:string" repeating="true">
  <doc>Filter by multiple status values</doc>
</param>

Parameter Styles:

template: Path parameters (e.g., /pets/{id})
query: Query string parameters (e.g., ?species=DOG)
header: HTTP headers (e.g., Authorization)

Representation Element

Describes request/response bodies:

<representation mediaType="application/json" element="Pet" />

Using WADL

Generate Client Code

WADL enables automatic client generation for various languages:

Java (JAX-RS)

# Using wadl2java tool
wadl2java -p com.example.petstore -o src/main/java petstore.wadl

// Generated client usage
PetstoreClient client = new PetstoreClient();
Pet pet = client.getPet("pet_fYrZzCW9E1WIOyGw");
System.out.println("Found: " + pet.getName());

Python (wadllib)

from wadllib.application import Application

# Load WADL
with open('petstore.wadl', 'r') as f:
    wadl = Application('https://api.petstoreapi.com/v1', f.read())

# Access resource
resource = wadl.get_resource_by_path('/pets/{id}')
method = resource.get_method('GET')

Validate API Calls

Use WADL to validate requests before sending:

def validate_request(path, method, params):
    """Validate request against WADL specification"""
    resource = wadl.get_resource_by_path(path)

    if not resource:
        raise ValueError(f"Unknown resource: {path}")

    method_def = resource.get_method(method)

    if not method_def:
        raise ValueError(f"Method {method} not allowed on {path}")

    # Validate parameters
    for param in method_def.params:
        if param.required and param.name not in params:
            raise ValueError(f"Required parameter missing: {param.name}")

API Examples

List Pets

WADL Definition:

<resource path="/pets">
  <method name="GET" id="listPets">
    <request>
      <param name="species" style="query" type="xsd:string">
        <doc>Filter by pet species</doc>
      </param>
      <param name="status" style="query" type="xsd:string" default="AVAILABLE">
        <doc>Filter by adoption status</doc>
      </param>
      <param name="page" style="query" type="xsd:int" default="1">
        <doc>Page number for pagination</doc>
      </param>
      <param name="limit" style="query" type="xsd:int" default="20">
        <doc>Number of items per page</doc>
      </param>
    </request>
    <response status="200">
      <representation mediaType="application/json" element="PetCollection" />
    </response>
  </method>
</resource>

HTTP Request:

curl "https://api.petstoreapi.com/v1/pets?species=DOG&status=AVAILABLE&page=1&limit=20"

Get Pet

WADL Definition:

<resource path="/pets/{id}">
  <param name="id" style="template" type="xsd:string" required="true">
    <doc>Unique identifier for the pet</doc>
  </param>
  <method name="GET" id="getPet">
    <response status="200">
      <representation mediaType="application/json" element="Pet" />
    </response>
    <response status="404" />
  </method>
</resource>

HTTP Request:

curl https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw

Create Pet

WADL Definition:

<method name="POST" id="createPet">
  <request>
    <representation mediaType="application/json" element="Pet" />
  </request>
  <response status="201">
    <representation mediaType="application/json" element="Pet" />
  </response>
</method>

HTTP Request:

curl -X POST https://api.petstoreapi.com/v1/pets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Buddy",
    "species": "DOG",
    "breed": "Golden Retriever",
    "ageMonths": 24,
    "status": "AVAILABLE"
  }'

Type System

WADL uses XML Schema Data Types (XSD) for parameter and representation types:

Basic Types

WADL Type	Description	Example
`xsd:string`	Text string	”Buddy”
`xsd:int`	32-bit integer	24
`xsd:long`	64-bit integer	9007199254740991
`xsd:float`	Single-precision float	123.45
`xsd:double`	Double-precision float	123.456789
`xsd:boolean`	Boolean value	true, false

Array Parameters

Use the repeating="true" attribute for array-type parameters:

<param name="status" style="query" type="xsd:string" repeating="true">
  <doc>Filter by multiple status values (e.g., ?status=AVAILABLE&status=PENDING)</doc>
</param>

Usage:

curl "https://api.petstoreapi.com/v1/inventories?status=AVAILABLE&status=PENDING"

Best Practices

1. Path Parameters at Resource Level

Define path parameters once at the resource level, not repeated in each method:

✅ CORRECT:
<resource path="/pets/{id}">
  <param name="id" style="template" type="xsd:string" required="true" />
  <method name="GET" id="getPet">
    <!-- No duplicate id parameter -->
  </method>
</resource>

❌ WRONG:
<resource path="/pets/{id}">
  <method name="GET" id="getPet">
    <request>
      <param name="id" style="template" type="xsd:string" required="true" />
    </request>
  </method>
</resource>

2. Use Meaningful IDs

Give each method a unique, descriptive ID:

<method name="GET" id="getPet">      <!-- ✅ Clear and descriptive -->
<method name="POST" id="createPet">  <!-- ✅ Indicates action -->
<method name="DELETE" id="deletePet"> <!-- ✅ Explicit operation -->

3. Document Everything

Include documentation for all elements:

<param name="species" style="query" type="xsd:string">
  <doc>Filter pets by species (DOG, CAT, RABBIT, BIRD, REPTILE, OTHER)</doc>
</param>

4. Specify Default Values

Include default values for optional parameters:

<param name="limit" style="query" type="xsd:int" default="20">
  <doc>Number of items per page (default: 20, max: 100)</doc>
</param>

WADL vs OpenAPI

Feature	WADL	OpenAPI
Format	XML	YAML/JSON
Readability	Machine-focused	Human-friendly
Schema Language	XML Schema (XSD)	JSON Schema
Tooling	Java-centric (JAX-RS)	Multi-language
Adoption	Legacy systems	Modern APIs
Documentation	XML comments	Rich markdown
Webhooks	Not supported	Supported (3.x+)
Use Case	Java web services	Cross-platform APIs

When to Choose WADL

Use WADL if:

✅ Working with Java/JAX-RS frameworks
✅ Integrating with legacy enterprise systems
✅ Client tools require WADL format
✅ Using XML-based toolchains

When to Choose OpenAPI

Use OpenAPI if:

✅ Building modern REST APIs
✅ Need human-readable documentation
✅ Want rich tooling ecosystem
✅ Require webhook/callback support
✅ Targeting multiple languages

Tools and Libraries

Java

JAX-RS (Jersey)

<!-- Maven dependency -->
<dependency>
    <groupId>org.glassfish.jersey.core</groupId>
    <artifactId>jersey-server</artifactId>
</dependency>

Apache CXF

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description</artifactId>
</dependency>

Python

wadllib

pip install wadllib

from wadllib.application import Application

with open('petstore.wadl', 'r') as f:
    app = Application('https://api.petstoreapi.com/v1', f.read())

Validation

xmllint (libxml2)

# Validate WADL XML structure
xmllint --noout petstore.wadl

# Pretty-print WADL
xmllint --format petstore.wadl

Migration Guide

From WADL to OpenAPI

If you’re migrating from WADL to OpenAPI:

Resource Mapping: WADL <resource> → OpenAPI paths
Method Mapping: WADL <method> → OpenAPI operation objects
Parameters: WADL <param> → OpenAPI parameters
Types: XSD types → JSON Schema types
Documentation: WADL <doc> → OpenAPI description

Example Conversion:

<!-- WADL -->
<resource path="/pets/{id}">
  <param name="id" style="template" type="xsd:string" required="true" />
  <method name="GET" id="getPet">
    <response status="200">
      <representation mediaType="application/json" element="Pet" />
    </response>
  </method>
</resource>

# OpenAPI
paths:
  /pets/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getPet
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

From OpenAPI to WADL

Our conversion script (scripts/oas32-to-wadl.mjs) automatically converts OpenAPI to WADL:

npm run oas32-to-wadl

Additional Resources

WADL Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.wadl
W3C WADL Spec: http://www.w3.org/Submission/wadl/
JAX-RS Documentation: https://eclipse-ee4j.github.io/jersey/
Related Protocols:

Support

For questions or issues with the WADL specification:

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

​Overview

​What is WADL?

​Key Features

​When to Use WADL

​WADL Structure

​Downloading the WADL Specification

​Direct Download

​Specification Details

​Understanding WADL Elements

​Application Element

​Resources Element

​Resource Element

​Method Element

​Parameter Element

​Representation Element

​Using WADL

​Generate Client Code

​Java (JAX-RS)

​Python (wadllib)

​Validate API Calls

​API Examples

​List Pets

​Get Pet

​Create Pet

​Type System

​Basic Types

​Array Parameters

​Best Practices

​1. Path Parameters at Resource Level

​2. Use Meaningful IDs

​3. Document Everything

​4. Specify Default Values

​WADL vs OpenAPI

​When to Choose WADL

​When to Choose OpenAPI

​Tools and Libraries

​Java

​Python

​Validation

​Migration Guide

​From WADL to OpenAPI

​From OpenAPI to WADL

​Additional Resources

​Support

Overview

What is WADL?

Key Features

When to Use WADL

WADL Structure

Downloading the WADL Specification

Direct Download

Specification Details

Understanding WADL Elements

Application Element

Resources Element

Resource Element

Method Element

Parameter Element

Representation Element

Using WADL

Generate Client Code

Java (JAX-RS)

Python (wadllib)

Validate API Calls

API Examples

List Pets

Get Pet

Create Pet

Type System

Basic Types

Array Parameters

Best Practices

1. Path Parameters at Resource Level

2. Use Meaningful IDs

3. Document Everything

4. Specify Default Values

WADL vs OpenAPI

When to Choose WADL

When to Choose OpenAPI

Tools and Libraries

Java

Python

Validation

Migration Guide

From WADL to OpenAPI

From OpenAPI to WADL

Additional Resources

Support