PetstoreAPI REST Protocol Guide

The Modern Petstore REST API is built with pure RESTful principles as the foundation. It serves as the reference implementation for proper API design.

Overview

Base URL: https://api.petstoreapi.com/v1

Protocol: HTTPS (REST over HTTP/1.1 or HTTP/2)

Content-Type: application/json

The REST API follows all REST architectural constraints:

✅ Client-Server: Clear separation of concerns

✅ Stateless: Each request contains all necessary information

✅ Cacheable: Responses include cache headers

✅ Uniform Interface: Consistent resource-oriented design

✅ Layered System: No client visibility into server architecture

RESTful Design Principles

1. Resource-Oriented URLs

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

2. Proper HTTP Methods

Method	Safe	Idempotent	Purpose
GET	✅	✅	Retrieve resources
POST	❌	❌	Create resources or submit forms
PUT	❌	✅	Full update (replace)
PATCH	❌	✅	Partial update
DELETE	❌	✅	Delete resources
QUERY	✅	✅	Complex queries with body (OpenAPI 3.2)

Example:

3. Correct HTTP Status Codes

Example:

4. Collection Wrappers

Never return bare arrays. Always wrap collections with metadata:

{
  "data": [
    { "id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Buddy", "species": "DOG" },
    { "id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Whiskers", "species": "CAT" }
  ],
  "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"
  }
}

5. Plural Resource Names

Always use plural nouns for collections:

Authentication

Bearer Token (JWT)

Include the token in the Authorization header:

Multi-Tenancy

Isolate data using the X-Tenant-ID header:

Endpoints

Pets

Advanced Search (QUERY Method)

OpenAPI 3.2 introduces the QUERY method for complex searches:

Orders

Error Handling

All errors follow RFC 9457 Problem Details format:

{
  "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"
    },
    {
      "field": "species",
      "message": "Must be one of: DOG, CAT, RABBIT, BIRD, REPTILE, OTHER",
      "code": "INVALID_ENUM_VALUE"
    }
  ]
}

Rate Limiting

The API uses IETF standard rate limiting headers:

When exceeded:

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute",
  "instance": "/v1/pets"
}

Caching

Resources include cache headers:

Conditional requests:

Resources include HATEOAS-style 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"
  }
}

Code Examples

TypeScript

Python

Best Practices

1. Follow HTTP Semantics

Use GET for retrieval (safe, idempotent)

Use POST for creation (not idempotent)

Use PUT for full replacement (idempotent)

Use PATCH for partial updates (idempotent)

Use DELETE for removal (idempotent)

2. Handle Status Codes Correctly

3. Respect Rate Limits

4. Use Conditional Requests

Interactive Documentation

Apidog UI: https://docs.petstoreapi.com

Swagger UI: https://api.petstoreapi.com/v1/swagger-ui.html

OpenAPI Spec: https://api.petstoreapi.com/v1/openapi.json

Overview#

RESTful Design Principles#

1. Resource-Oriented URLs#

2. Proper HTTP Methods#

3. Correct HTTP Status Codes#

4. Collection Wrappers#

5. Plural Resource Names#

Authentication#

Bearer Token (JWT)#

Multi-Tenancy#

Endpoints#

Pets#

Advanced Search (QUERY Method)#

Orders#

Error Handling#

Rate Limiting#

Caching#

Navigation Links#

Code Examples#

TypeScript#

Python#

Best Practices#

1. Follow HTTP Semantics#

2. Handle Status Codes Correctly#

3. Respect Rate Limits#

4. Use Conditional Requests#

Interactive Documentation#

Related Resources#