Modern Petstore API: A New Gold Standard for OpenAPI

Building the API Example the Industry Deserves

The Problem with the Old Petstore

For over a decade, every developer learning OpenAPI (formerly Swagger) has encountered the same example: the Petstore API. While it served its purpose as a teaching tool, the original Petstore has become outdated, failing to reflect modern API design practices and the full capabilities of OpenAPI 3.x specifications.

🚨 Critical Issue: Violation of RESTful Principles

The biggest problem? The old Petstore doesn't even follow basic RESTful design principles. This is catastrophic because it teaches developers anti-patterns that they carry into production systems.

Here are the specific RESTful violations in the original Swagger Petstore:

1. Plural vs Singular Resource Names

Problem: Inconsistent naming confuses developers and breaks conventions.

2. Non-RESTful URL Design

Problem: URLs should represent resources (nouns), not actions (verbs).

3. Missing Standard HTTP Status Codes

Problem: Incorrect status codes confuse clients and break HTTP semantics.

3. Wrong HTTP Methods for Authentication

Problem: The old Petstore uses GET for login, which:

Exposes passwords in URL query parameters (visible in browser history, server logs, referrer headers)

Violates the HTTP specification (GET must be safe and idempotent)

Creates a massive security vulnerability

Is NOT cacheable despite using GET

5. No Collection Wrappers

❌ BAD (Old Petstore):
GET /pets → Returns bare array
[
  {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
  {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
]

✅ GOOD (Modern Petstore):
GET /pets → Returns wrapped collection with metadata
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "...",
    "next": "..."
  }
}

Problem: Bare arrays can't be extended with metadata, breaking forward compatibility.

Introducing Modern Petstore API

We've built a completely reimagined Petstore API from the ground up—one that showcases current best practices and demonstrates the full power of OpenAPI 3.2. This isn't just an update; it's a comprehensive reference implementation designed to be the new industry standard.

Our Mission

Create a pet store API that:

✅ Demonstrates every OpenAPI 3.2 feature with production-ready examples

✅ Follows current web standards (RFC 9457, IETF rate limiting, ISO formats)

✅ Provides realistic business logic (payments, webhooks, AI features)

✅ Includes comprehensive code samples across multiple languages

✅ Serves as a learning resource for API designers and developers

✅ Can be deployed to production with minimal modifications

What Makes It Modern?

✅ Multi-Protocol Architecture

Modern PetstoreAPI is the only reference implementation supporting multiple API protocols and specifications:

Unlike the classic Petstore (REST-only) and other examples (typically REST-only), we provide a complete multi-protocol architecture:

REST (OpenAPI 3.2) - Resource-oriented API following pure RESTful principles

Webhooks - Event-driven HTTP callbacks for asynchronous notifications

Callbacks - OpenAPI 3.x callback patterns for async request-response flows

SSE (Server-Sent Events) - Real-time streaming for live updates and AI responses

WebSocket - Full-duplex bidirectional real-time communication

Socket.IO - WebSocket with automatic fallback and enhanced features

MQTT - Lightweight publish-subscribe messaging protocol for IoT devices

MCP (Model Context Protocol) - AI assistant integration for Claude Desktop and other MCP clients

GraphQL - Flexible query language for complex data requirements

gRPC - High-performance RPC protocol for microservices

AsyncAPI 3.0 - Event-driven architecture specification

WSDL - SOAP web services for enterprise integration

WADL - Web Application Description Language support

This demonstrates that modern APIs can serve multiple client types and use cases from a single backend. Choose REST for simplicity, webhooks/callbacks for event-driven integration, SSE for real-time streaming, WebSocket/Socket.IO/MQTT for bidirectional real-time communication, MCP for AI assistant integration, GraphQL for flexibility, gRPC for performance, AsyncAPI for event-driven architecture, or SOAP/WADL for legacy integration.

✅ First and Foremost: True RESTful Design

This is the foundation everything else builds on. We follow RESTful principles rigorously:

1. Correct HTTP Methods for Every Operation

Every method follows HTTP semantics:

GET: Safe (no side effects) and idempotent

POST: Create resources, submit forms, non-idempotent operations

PUT/PATCH: Idempotent updates

DELETE: Idempotent removal

2. Proper HTTP Status Codes

We use the right status code for every situation:

Example response with proper status code:

3. Resource-Oriented URL Design

URLs represent resources (nouns), not actions (verbs):

For complex operations that don't fit CRUD, we use:

Sub-resources: POST /orders/{id}/payment

Query parameters: GET /pets?status=AVAILABLE&species=DOG

QUERY method (OpenAPI 3.2): QUERY /pets/search with request body

4. Consistent Plural Nouns for Collections

This consistency makes APIs predictable and intuitive.

5. Uniform Path Parameter Naming

Why this matters: Clients can predict URL patterns without reading docs.

6. Collection Wrappers with Pagination

Every collection endpoint returns a consistent structure:

{
  "data": [
    { "id": "pet_fYrZzCW9E1WIOyGw", "name": "Whiskers", ... },
    { "id": "pet_fYrZzCW9E1WIOyGw", "name": "Buddy", ... }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 145,
    "totalPages": 8
  },
  "links": {
    "self": "https://api.petstoreapi.com/v1/pets?page=1",
    "next": "https://api.petstoreapi.com/v1/pets?page=2",
    "prev": null,
    "first": "https://api.petstoreapi.com/v1/pets?page=1",
    "last": "https://api.petstoreapi.com/v1/pets?page=8"
  }
}

Benefits:

Never break pagination: Add totalItems later without breaking clients

Navigation links: Clients follow links, not construct URLs

Consistent structure: Every collection works the same way

Every resource includes navigational links:

{
  "id": "pet_fYrZzCW9E1WIOyGw",
  "name": "Whiskers",
  "species": "CAT",
  "status": "AVAILABLE",
  "links": {
    "self": "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw",
    "adopt": "https://api.petstoreapi.com/v1/adoptions",
    "images": "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw/images"
  }
}

Clients can:

Discover available operations

Navigate without hardcoding URLs

Evolve independently from URL changes

8. Content Negotiation

Support multiple representations:

We standardize on JSON but the pattern supports future formats.

9. Idempotency Where Required

Operations that should be idempotent are:

This allows safe retries on network failures.

10. Caching Support

We include proper cache headers:

This reduces bandwidth and improves performance.

🆕 OpenAPI 3.2 Exclusive Features

Beyond RESTful fundamentals, we leverage the latest OpenAPI 3.2 specification features:

Hierarchical Tags

Organize your API endpoints with structured tagging:

This creates a clean hierarchy in documentation tools, making large APIs easier to navigate.

QUERY HTTP Method

For complex searches that exceed URL length limits:

OAuth Device Flow

Perfect for smart TVs, IoT devices, and kiosks:

Reusable Path Items

DRY principle for consistent resource patterns:

📚 Modern API Standards

We don't just follow OpenAPI—we implement current web standards across the board:

RFC 9457: Problem Details for HTTP APIs

No more generic error messages. Every error response follows the standard:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors",
  "instance": "/v1/pets",
  "errors": [
    {
      "field": "ageMonths",
      "message": "Must be a positive number",
      "code": "INVALID_FORMAT"
    }
  ]
}

Notice how it provides:

Structured field-level errors - developers know exactly what to fix

Unique error type URLs - link to detailed documentation

Machine-readable error codes - enable programmatic handling

IETF Rate Limiting Headers

We use the modern standard, not legacy X-RateLimit headers:

ISO Standard Data Formats

ISO 3166-1 alpha-2: Country codes (US, GB, CA)

ISO 4217: Currency codes (USD, EUR, GBP)

ISO 8601 / RFC 3339: Timestamps (2025-12-17T08:00:00Z)

This ensures international compatibility and eliminates ambiguity.

🎨 Real-World API Patterns

Modern APIs aren't simple CRUD operations. We demonstrate complex, production-ready patterns:

Polymorphic Payment Sources

Support multiple payment methods with discriminators:

{
  "amount": 150.00,
  "currency": "USD",
  "source": {
    "object": "CARD",
    "name": "Jane Doe",
    "number": "4242424242424242",
    "expMonth": 12,
    "expYear": 2025,
    "cvc": "123"
  }
}

// Or pay with bank account
{
  "amount": 150.00,
  "currency": "USD",
  "source": {
    "object": "BANK_ACCOUNT",
    "accountHolderName": "Jane Doe",
    "routingNumber": "110000000",
    "accountNumber": "000123456789",
    "accountType": "CHECKING"
  }
}

The OpenAPI spec uses discriminators to validate the correct fields based on object type:

Never return bare arrays. Every collection response includes:

{
  "data": [
    {
      "id": "pet_fYrZzCW9E1WIOyGw",
      "species": "CAT",
      "name": "Whiskers",
      "links": {
        "self": "https://api.petstoreapi.com/v1/pets/pet_fYrZzCW9E1WIOyGw",
        "adopt": "https://api.petstoreapi.com/v1/adoptions"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "https://api.petstoreapi.com/v1/pets?page=1",
    "next": "https://api.petstoreapi.com/v1/pets?page=2",
    "last": "https://api.petstoreapi.com/v1/pets?page=3"
  }
}

Benefits:

Pagination metadata - clients know exactly where they are

Navigation links - API is self-documenting and discoverable

Consistent structure - all collections follow the same pattern

Webhooks for Event-Driven Architecture

OpenAPI 3.x supports webhook definitions. We demonstrate real-world events:

Your application receives events when important actions occur—no polling needed.

Server-Sent Events (SSE) for Real-Time Streaming

AI features need streaming responses. We demonstrate with a Pet Adoption Advisor:

The OpenAPI spec documents the SSE format with text/event-stream media type.

💻 Developer Experience

Great APIs are easy to use. We've focused heavily on developer experience:

Multi-Language Code Examples

Every major operation includes x-codeSamples with ready-to-use examples:

TypeScript:

Python:

cURL:

Workflow Descriptions

Every operation includes business context, not just technical details:

External Documentation Links

Complex features link to detailed guides:

Technical Architecture

Built for Scalability

We've chosen a modern, performant stack:

Node.js: Industry-standard runtime

Hono: Fast, lightweight web framework

TypeScript: End-to-end type safety

Docker: Containerized deployment anywhere

This isn't a toy example—it's production infrastructure.

Type Safety Everywhere

Comprehensive Validation

We use unevaluatedProperties: false to catch unexpected fields:

This prevents clients from sending invalid data and makes API evolution explicit.

Comparison: Old vs. New

Let's see how we stack up against the original Swagger Petstore and other modern examples. RESTful compliance is listed first as it's the foundation:

Feature	Old Petstore	Train Travel API	Modern Petstore
🔴 RESTful: HTTP Methods	❌ GET for login/logout	✅ POST for mutations	✅ Correct methods everywhere
🔴 RESTful: Status Codes	❌ 200 for POST/DELETE	✅ Proper codes	✅ 201/204/4xx/5xx properly
🔴 RESTful: URL Design	❌ /findByStatus (verbs)	✅ Resource-oriented	✅ Pure resource nouns
🔴 RESTful: Plural Resources	❌ /pet (singular)	✅ /trips (plural)	✅ /pets, /users, /orders
🔴 RESTful: Path Parameters	❌ /user/{username} mixed	✅ Consistent	✅ {id} uniformly
🔴 RESTful: Collections	❌ Bare arrays	✅ Wrapped	✅ Wrapped + pagination + links
🔴 RESTful: Idempotency	❌ Not documented	✅ Documented	✅ Explicit + safe retries
OpenAPI Version	2.0	3.1.0	3.2.0 ✅
Error Standard	Custom	RFC 9457	RFC 9457 + Field Details ✅
Rate Limiting	X-RateLimit	RateLimit-*	RateLimit-* ✅
Auth Methods	API Key in URL	OAuth	OAuth + Bearer/JWT ✅
OAuth Flows	None	Authorization Code	Auth Code + Device Flow ✅
Webhooks	None	Basic	Complete with Security ✅
Real-time (SSE)	None	None	Full SSE Implementation ✅
QUERY Method	None	None	Yes (OpenAPI 3.2) ✅
Hierarchical Tags	None	Flat	Full Hierarchy ✅
Code Samples	None	Basic	Multi-language x-codeSamples ✅
Polymorphic Types	None	Basic	Discriminators with Mapping ✅
Protocol Support	REST only	REST only	REST + SSE + MCP + GraphQL + gRPC + AsyncAPI + WSDL + WADL ✅
Production Ready	No	Partial	Fully Deployable ✅

Result: We lead in every category, with RESTful compliance being our strongest differentiator.

The Modern Petstore follows 100% of RESTful principles plus modern extensions like QUERY method and structured navigation.

Real-World Use Cases

This isn't just an example—it's a template for building production APIs:

🐾 Pet Adoption Platform

The obvious use case. Organizations can fork this and customize:

Add shelter locations with geospatial search

Integrate with local regulations and licensing

Add foster care management

Implement application review workflows

🏥 Healthcare Appointment Systems

The patterns translate perfectly:

Pets → Patients

Adoption Status → Appointment Status

Medical Info → Patient Records

Webhooks for appointment reminders

🛒 E-Commerce Platforms

Same structural patterns:

Pets → Products

Adoption → Purchase

Species/Breed → Categories

Polymorphic payments already implemented

📚 Resource Booking Systems

Libraries, equipment rentals, room bookings:

Pets → Resources

Availability Status → Booking Status

User accounts and authentication ready

Search and filtering patterns established

Getting Started

Quick Start

Explore the API

View Documentation

Swagger UI: http://localhost:8787/v1/docs

AsyncAPI UI: http://localhost:8787/v1/async-docs

OpenAPI Spec: http://localhost:8787/v1/openapi.json

AsyncAPI Spec: http://localhost:8787/v1/asyncapi.json

Learning Resources

For API Designers

Study our OpenAPI spec to learn:

How to structure complex schemas with discriminators

When to use readOnly vs writeOnly

How to document workflows with descriptions

How to organize tags hierarchically

When to use references vs inline schemas

For API Developers

Learn implementation patterns:

Structured error handling with RFC 9457

Rate limiting middleware

OAuth 2.0 implementation

Webhook delivery with retries

SSE streaming for real-time data

For Technical Writers

See how to document:

Complex authentication flows

Multi-step business workflows

Error scenarios with examples

Code samples in multiple languages

External resource links

Design Principles

These principles guided every decision:

1. Standards Over Custom

We prefer established standards (RFC 9457, ISO codes, IETF headers) over inventing our own. Standards are:

Already documented

Widely understood

Supported by tools

Battle-tested

2. Production-Ready Over Simplified

Examples that are "too simple" teach bad habits. We include:

Proper error handling

Rate limiting

Security models

Validation

Pagination

3. Realistic Over Theoretical

We model actual business logic:

Payment processing with multiple methods

Multi-step workflows (adoption application → approval → completion)

Webhook event delivery

AI integration

4. Modern Over Compatible

We target the latest specifications:

OpenAPI 3.2 (not 3.0 or 2.0)

JSON Schema 2020-12

Current RFC standards

If you need older versions, this shows what you're missing.

5. Complete Over Minimal

Every feature is fully implemented:

All CRUD operations

Search and filtering

Pagination

Webhooks

Streaming responses

No "TODO" comments or stub implementations.

What's Next?

We're continuously improving the Modern Petstore API:

Coming Soon

AsyncAPI 3.0 Specification: Complete async/event documentation

Arazzo Workflows: Step-by-step workflow definitions

GraphQL Endpoint: Demonstrate REST + GraphQL coexistence

More Code Samples: Go, Java, PHP, Ruby

Performance Benchmarks: Quantified edge performance metrics

Video Tutorials: Walkthrough of key features

Community

This project thrives on community contributions:

GitHub Discussions: Share use cases and ask questions

Issues: Report bugs or request features

Pull Requests: Contribute improvements

Blog Posts: Write about how you're using the API

Translations: Help document in other languages

Conclusion

The Modern Petstore API isn't just an update—it's a reimagining of what an API example should be:

✅ Complete OpenAPI 3.2 showcase
✅ Current web standards throughout
✅ Production-ready architecture
✅ Real-world business patterns
✅ Comprehensive documentation
✅ Multi-language code samples
✅ Deployable to Docker/Node.js

Whether you're learning OpenAPI, designing a new API, evaluating API tools, or teaching others, the Modern Petstore API provides a comprehensive, realistic reference.

The classic Petstore served us well for over a decade. Now it's time for a new standard.

Try It Now

Live API: https://api.petstoreapi.com
Interactive Docs: https://api.petstoreapi.com/v1/docs
GitHub: https://github.com/petstoreapi/PetstoreAPI
OpenAPI Spec: https://api.petstoreapi.com/v1/openapi.json

Give it a star ⭐ if you find it useful!

About the Project

The Modern Petstore API is an open-source project created to demonstrate best practices in API design. It's maintained by the community and welcomes contributions from developers worldwide.

Built with ❤️ using:

OpenAPI 3.2

TypeScript

Hono

Node.js / Docker

Modern Web Standards

License: MIT

Last updated: December 2025

Modern Petstore API: A New Gold Standard for OpenAPI

The Problem with the Old Petstore#

🚨 Critical Issue: Violation of RESTful Principles#

1. Plural vs Singular Resource Names#

2. Non-RESTful URL Design#

3. Missing Standard HTTP Status Codes#

3. Wrong HTTP Methods for Authentication#

5. No Collection Wrappers#

Other Critical Problems#

Introducing Modern Petstore API#

Our Mission#

What Makes It Modern?#

✅ Multi-Protocol Architecture#

✅ First and Foremost: True RESTful Design#

1. Correct HTTP Methods for Every Operation#

2. Proper HTTP Status Codes#

3. Resource-Oriented URL Design#

4. Consistent Plural Nouns for Collections#

5. Uniform Path Parameter Naming#

6. Collection Wrappers with Pagination#

7. Navigation Links#

8. Content Negotiation#

9. Idempotency Where Required#

10. Caching Support#

🆕 OpenAPI 3.2 Exclusive Features#

Hierarchical Tags#

QUERY HTTP Method#

OAuth Device Flow#

Reusable Path Items#

📚 Modern API Standards#

RFC 9457: Problem Details for HTTP APIs#

IETF Rate Limiting Headers#

ISO Standard Data Formats#

🎨 Real-World API Patterns#

Polymorphic Payment Sources#

Collection Wrappers & Navigation#

Webhooks for Event-Driven Architecture#

Server-Sent Events (SSE) for Real-Time Streaming#

💻 Developer Experience#

Multi-Language Code Examples#

Workflow Descriptions#

External Documentation Links#

Technical Architecture#

Built for Scalability#

Type Safety Everywhere#

Comprehensive Validation#

Comparison: Old vs. New#

Real-World Use Cases#

🐾 Pet Adoption Platform#

🏥 Healthcare Appointment Systems#

🛒 E-Commerce Platforms#

📚 Resource Booking Systems#

Getting Started#

Quick Start#

Explore the API#

View Documentation#

Learning Resources#

For API Designers#

For API Developers#

For Technical Writers#

Design Principles#

1. Standards Over Custom#

2. Production-Ready Over Simplified#

3. Realistic Over Theoretical#

4. Modern Over Compatible#

5. Complete Over Minimal#

What's Next?#

Coming Soon#

Community#

Conclusion#

Try It Now#

About the Project#