API Protocols Guide

Modern Petstore API supports multiple API protocols and specifications, making it the most comprehensive reference implementation available. Choose the protocol that best fits your use case.

Quick Protocol Selection

Protocol	Best For	Communication Pattern	Complexity
REST	Standard CRUD operations	Request/Response	Low
SSE	Real-time streaming, AI responses	Server → Client (unidirectional)	Low
WebSocket	Bidirectional real-time communication	Client ↔ Server (full-duplex)	Medium
Socket.IO	Real-time with automatic fallback	Client ↔ Server (with fallback)	Medium
MQTT	IoT devices, low-bandwidth scenarios	Publish/Subscribe	Medium
Webhooks	Event-driven notifications	Server → Client (HTTP callbacks)	Low
Callbacks	Async operation status	Server → Client (dynamic URLs)	Medium
GraphQL	Flexible data queries	Request/Response	Medium
gRPC	High-performance microservices	Request/Response (binary)	High
MCP	AI assistant integration	Request/Response	Medium

Protocol Details

1. REST API (HTTPS)

The foundation - Standard HTTP-based API following RESTful principles.

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

When to Use:

Standard CRUD operations (Create, Read, Update, Delete)

Resource-oriented operations

Stateful client-server communication

When you need caching (HTTP cache headers)

Key Features:

✅ Pure RESTful design (proper HTTP methods, status codes)

✅ Resource-oriented URLs (/pets, /users, /orders)

✅ Collection wrappers with pagination

✅ RFC 9457 error responses

✅ IETF rate limiting headers

Quick Example:

Documentation:

OpenAPI Specification

REST API Guide

Quick Start Guide

2. Server-Sent Events (SSE)

Real-time streaming - Server pushes data to client over HTTP.

Endpoint: https://api.petstoreapi.com/v1/chat/completions (with stream: true)

When to Use:

Real-time updates from server to client

AI chat streaming responses

Live notifications

When you only need server → client communication

Key Features:

✅ Built on HTTP (no new infrastructure needed)

✅ Automatic reconnection handling

✅ Text-based, easy to debug

✅ One-way communication (server → client)

Quick Example:

Documentation:

SSE Protocol Guide

Quick Start Guide

3. WebSocket

Full-duplex communication - Persistent connection for bidirectional real-time messaging.

Endpoint: wss://api.petstoreapi.com/v1/ws/chat

When to Use:

Real-time bidirectional communication

Customer support chat systems

Collaborative applications

Low-latency updates required

Key Features:

✅ Full-duplex (send and receive simultaneously)

✅ Low latency

✅ Persistent connection

✅ Binary and text data support

Quick Example:

Documentation:

WebSocket Protocol Guide

Quick Start Guide

4. Socket.IO

WebSocket with fallbacks - Real-time communication with automatic fallback.

Endpoint: wss://api.petstoreapi.com

When to Use:

Real-time features that must work everywhere

Need automatic fallback (polling) when WebSocket unavailable

Building customer support chat

Need room-based messaging

Key Features:

✅ Automatic fallback to long-polling

✅ Room-based messaging

✅ Reconnection handling

✅ Broadcast capabilities

Quick Example:

Documentation:

Socket.IO Protocol Guide

Quick Start Guide

5. MQTT (Message Queuing Telemetry Transport)

Lightweight IoT protocol - Publish/subscribe for resource-constrained devices.

Endpoint: mqtts://mqtt.petstoreapi.com:8883

When to Use:

IoT devices and sensors

Low-bandwidth, unreliable networks

Battery-powered devices

Many devices publishing data

Key Features:

✅ Extremely lightweight (small packet overhead)

✅ Publish/Subscribe pattern

✅ QoS levels (guaranteed delivery)

✅ Works on unreliable networks

Quick Example:

Documentation:

MQTT Protocol Guide

MQTT Quick Start

6. Webhooks

Event-driven HTTP callbacks - Server pushes events to your endpoints.

When to Use:

Real-time notifications for events

Order status updates

Payment confirmations

Pet adoption notifications

Key Features:

✅ Server initiates the request

✅ Your endpoint receives events

✅ Retry logic on failure

✅ HMAC signature verification

Quick Example:

Documentation:

Webhooks Guide

AsyncAPI Specification

7. GraphQL

Flexible query language - Request exactly the data you need.

Endpoint: https://api.petstoreapi.com/v1/graphql

When to Use:

Complex, nested data requirements

Mobile applications (reduce payload size)

Multiple resources in single request

Flexible, self-documenting API

Key Features:

✅ Request exactly what you need

✅ Single request for multiple resources

✅ Strongly typed schema

✅ Introspection (self-documenting)

Quick Example:

Documentation:

GraphQL Protocol Guide

8. gRPC

High-performance RPC - Binary protocol for microservices.

When to Use:

High-performance requirements

Microservice-to-microservice communication

Strongly typed contracts needed

Low latency, high throughput

Key Features:

✅ Binary serialization (Protocol Buffers)

✅ High performance

✅ Strong typing with .proto files

✅ Built-in code generation

Quick Example:

Documentation:

gRPC Protocol Guide

9. MCP (Model Context Protocol)

AI assistant integration - Connect Claude Desktop and other AI assistants.

When to Use:

Building AI-powered tools

Claude Desktop integration

AI assistant needs to query your data

Context-aware AI interactions

Key Features:

✅ Standard protocol for AI tools

✅ Resource and prompt definitions

✅ Native Claude Desktop support

✅ Context-aware responses

Quick Example:

{
  "name": "petstore-mcp-server",
  "command": "node",
  "args": ["dist/index.js"],
  "env": {
    "PETSTORE_API_KEY": "your_api_key",
    "PETSTORE_API_BASE": "https://api.petstoreapi.com/v1"
  }
}

Documentation:

MCP Integration Guide

Claude MCP Documentation

Protocol Comparison

When to Use Each Protocol

┌─────────────────────────────────────────────────────────────────┐
│                     Choose Your Protocol                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Need standard CRUD operations?                                 │
│  → Use REST                                                     │
│                                                                  │
│  Need real-time updates from server?                            │
│  → Use SSE (one-way) or WebSocket (two-way)                     │
│                                                                  │
│  Building chat/collaboration?                                   │
│  → Use WebSocket or Socket.IO                                   │
│                                                                  │
│  IoT devices or constrained networks?                           │
│  → Use MQTT                                                     │
│                                                                  │
│  Need event notifications?                                      │
│  → Use Webhooks                                                 │
│                                                                  │
│  Complex, flexible data queries?                                │
│  → Use GraphQL                                                  │
│                                                                  │
│  High-performance microservices?                                │
│  → Use gRPC                                                     │
│                                                                  │
│  AI assistant integration?                                      │
│  → Use MCP                                                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Performance Characteristics

Protocol	Latency	Throughput	Overhead	Scalability
REST	Medium	Medium	High	Excellent
SSE	Low	Medium	Low	Good
WebSocket	Very Low	High	Very Low	Good
Socket.IO	Low	High	Low	Good
MQTT	Low	Medium	Very Low	Excellent
GraphQL	Medium	Medium	Medium	Good
gRPC	Very Low	Very High	Very Low	Excellent

Getting Started

For Beginners

Start with REST - It's the most common and well-documented

Explore the Quick Start Guide

Check out interactive documentation

For Specific Use Cases

Web Applications: REST + SSE/WebSocket

Mobile Apps: REST + GraphQL

IoT Devices: MQTT

Microservices: gRPC

AI Integration: MCP

Specifications

OpenAPI 3.2 (REST, SSE, Webhooks): JSON | YAML

AsyncAPI 3.0 (WebSocket, MQTT, Kafka): JSON | YAML

Need help choosing? Contact us at support@petstoreapi.com

Quick Protocol Selection#

Protocol Details#

1. REST API (HTTPS)#

2. Server-Sent Events (SSE)#

3. WebSocket#

4. Socket.IO#

5. MQTT (Message Queuing Telemetry Transport)#

6. Webhooks#

7. GraphQL#

8. gRPC#

9. MCP (Model Context Protocol)#

Protocol Comparison#

When to Use Each Protocol#

Performance Characteristics#

Getting Started#

For Beginners#

For Specific Use Cases#

Specifications#

Related Resources#

Quick Protocol Selection

Protocol Details

1. REST API (HTTPS)

2. Server-Sent Events (SSE)

3. WebSocket

4. Socket.IO

5. MQTT (Message Queuing Telemetry Transport)

6. Webhooks

7. GraphQL

8. gRPC

9. MCP (Model Context Protocol)

Protocol Comparison

When to Use Each Protocol

Performance Characteristics

Getting Started

For Beginners

For Specific Use Cases

Specifications

Related Resources