Modern Pet Store API

From outdated examples to production-ready patterns - How we built the most comprehensive OpenAPI 3.2 demonstration with real-world features developers actually need.

🎯 TL;DR - Why This Matters to You#

🔥 The Problem: Your API Examples Are Teaching You Bad Habits#

What's Wrong with Traditional Petstore Examples?#

// What petstore teaches you ❌
GET /pets
[{"id": 1, "name": "Rex"}, {"id": 2, "name": "Felix"}]

// What petstore teaches you ❌
HTTP 400
{"error": "Invalid input"}

💡 Our Solution: Modern Pet Store API#

Design Principles#

🚀 OpenAPI 3.2.0: The Features That Change Everything#

🆕 Feature 1: Hierarchical Tags (Finally!)#

🆕 Feature 2: QUERY HTTP Method (Game Changer)#

🆕 Feature 3: OAuth Device Authorization Flow#

🆕 Feature 4: Reusable Media Types (DRY Principle)#

🎯 Production Patterns That Actually Matter#

Pattern 1: RFC 9457 Problem Details (Stop Using Generic Errors!)#

HTTP 400 Bad Request
{
  "error": "Validation failed"
}

HTTP 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors",
  "instance": "/v1/pets",
  "errors": [
    {
      "field": "age_months",
      "message": "Must be a positive integer",
      "code": "invalid_type"
    },
    {
      "field": "species",
      "message": "Must be one of: dog, cat, rabbit, bird, reptile, other",
      "code": "invalid_enum"
    }
  ]
}

Pattern 2: Collection Wrappers (Never Return Bare Arrays!)#

GET /pets
[
  {"id": "pet_cat_5x7k9m", "name": "Whiskers"},
  {"id": "pet_dog_8n2q4w", "name": "Max"}
]

GET /v1/pets
{
  "data": [
    {
      "id": "pet_cat_5x7k9m",
      "species": "cat",
      "name": "Whiskers",
      "age_months": 18,
      "status": "available",
      "links": {
        "self": "https://api.petstoreapi.com/v1/pets/pet_cat_5x7k9m",
        "adopt": "https://api.petstoreapi.com/v1/adoptions"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total_items": 145,
    "total_pages": 8
  },
  "links": {
    "self": "https://api.petstoreapi.com/v1/pets?page=1",
    "first": "https://api.petstoreapi.com/v1/pets?page=1",
    "last": "https://api.petstoreapi.com/v1/pets?page=8",
    "next": "https://api.petstoreapi.com/v1/pets?page=2"
  }
}

Pattern 3: Semantic IDs (Stop Using Sequential Numbers!)#

{"id": 1}
{"id": 2}
{"id": 3}

{"id": "pet_cat_5x7k9m"}
{"id": "pet_dog_8n2q4w"}
{"id": "ord_2024_x8k3p9"}

Pattern 4: IETF Rate Limiting (Let Clients Behave Responsibly)#

💻 Production-Ready Implementation Details#

Technology Stack#

📊 Before & After Comparison#

🎓 What You'll Learn#

For API Designers#

For Developers#

For Architects#

🚀 Get Started in 2 Minutes#

1. Try the Live API#

2. Explore Interactive Docs#

3. Clone and Run Locally#

4. Deploy Your Own (30 seconds!)#

🌟 Real-World Use Cases#

Use Case 1: Pet Adoption Platform#

Use Case 2: University API Design Course#

"Finally, an example that shows students how APIs should be built in 2025. The OpenAPI 3.2 features and production patterns saved weeks of curriculum development."

Use Case 3: Enterprise API Modernization#

"We standardized on these patterns across 50+ internal APIs. The RFC 9457 error handling alone improved our developer satisfaction scores by 35%."

📚 Additional Resources#

Deep Dives#

Standards & RFCs#

Community#

🎯 Your Next Steps#

📣 Spread the Word#

🙏 Acknowledgments#