API Protocols Guide - Modern PetstoreAPI Docs

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
WADL	Java/JAX-RS web services	Request/Response	Medium
WSDL	SOAP enterprise integration	Request/Response	High
RAML	API design and documentation	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:

# List available pets
curl https://api.petstoreapi.com/v1/pets?status=AVAILABLE

# Create a new pet
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"
  }'

Documentation:

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:

curl -N -X POST https://api.petstoreapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "messages": [{"role": "USER", "content": "Tell me about Golden Retrievers"}],
    "model": "PET_ADVISOR_1",
    "stream": true
  }'

Documentation:

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:

const ws = new WebSocket('wss://api.petstoreapi.com/v1/ws/chat?token=YOUR_JWT_TOKEN');

ws.addEventListener('open', () => {
  // Send a message
  ws.send(JSON.stringify({
    type: 'chatMessage',
    payload: {
      conversationId: 'conv_abc123',
      senderId: 'user_xyz789',
      content: 'Hello, I need help with my order',
      timestamp: new Date().toISOString()
    }
  }));
});

// Listen for messages
ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
});

Documentation:

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:

import { io } from 'socket.io-client';

const socket = io('wss://api.petstoreapi.com', {
  auth: { token: 'YOUR_JWT_TOKEN' },
  transports: ['websocket']
});

// Join a chat room
socket.emit('joinChat', {
  conversationId: 'conv_abc123',
  userId: 'user_xyz789'
});

// Send a message
socket.emit('chatMessage', {
  conversationId: 'conv_abc123',
  content: 'I need help with my order'
});

// Listen for incoming messages
socket.on('chatMessage', (data) => {
  console.log('New message:', data.content);
});

Documentation:

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:

import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    print(f"Topic: {msg.topic}")
    print(f"Message: {msg.payload.decode()}")

client = mqtt.Client(client_id="petstore-iot-device-001")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()

client.on_connect = lambda c, u, f: c.subscribe("orders/+/status")
client.on_message = on_message

client.connect("mqtt.petstoreapi.com", 8883, 60)
client.loop_forever()

Documentation:

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:

// Your webhook endpoint
app.post('/webhooks/petstore', (req, res) => {
  const signature = req.headers['x-petstore-signature'];
  const payload = req.body;

  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Handle event
  switch (payload.eventType) {
    case 'pet.adopted':
      console.log(`Pet ${payload.data.pet.id} was adopted!`);
      break;
    case 'order.created':
      console.log(`New order: ${payload.data.order.id}`);
      break;
  }

  res.sendStatus(200);
});

Documentation:

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:

curl -X POST https://api.petstoreapi.com/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "query": "query GetAvailablePets { pets(status: AVAILABLE) { id name species breed ageMonths } }"
  }'

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:

import grpc
from petstore_pb2 import GetPetRequest
from petstore_pb2_grpc import PetServiceStub

channel = grpc.secure_channel('api.petstoreapi.com:443', credentials)
stub = PetServiceStub(channel)

request = GetPetRequest(id="pet_fYrZzCW9E1WIOyGw")
response = stub.GetPet(request)

print(f"Pet: {response.name}, {response.species}")

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:

10. WADL (Web Application Description Language)

XML-based API description - Machine-readable format for HTTP-based web services. Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.wadl When to Use:

Java/JAX-RS web services
Legacy enterprise system integration
Client code generation for Java
XML-based toolchains

Key Features:

✅ XML Schema type system
✅ Resource-oriented descriptions
✅ Automatic client generation
✅ JAX-RS framework support

Quick Example:

<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>
  </method>
</resource>

Documentation:

11. WSDL (Web Services Description Language)

SOAP web services - Enterprise integration with formal contracts. Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.wsdl Endpoint: https://api.petstoreapi.com/v1/soap When to Use:

Enterprise system integration (SAP, Oracle)
Formal service contracts (SLA agreements)
.NET or Java enterprise frameworks
Built-in security requirements (WS-Security)
Transactional operations

Key Features:

✅ XML Schema strong typing
✅ WS-* standards (Security, Transactions)
✅ SOAP envelope messaging
✅ Wide enterprise tooling support

Quick Example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPetRequest>
      <id>pet_fYrZzCW9E1WIOyGw</id>
    </GetPetRequest>
  </soap:Body>
</soap:Envelope>

Documentation:

12. RAML (RESTful API Modeling Language)

Design-first API specification - YAML-based API description with reusable components. Specification: https://api.petstoreapi.com/v1/specs/modern-petstore.raml When to Use:

API design before implementation
MuleSoft Anypoint Platform integration
Highly modular API specifications
Strong type validation needed
Building APIs with consistent patterns

Key Features:

✅ YAML-based, human-readable
✅ Reusable types, traits, and resource types
✅ Design-first approach
✅ Auto-generated documentation
✅ Modular specifications

Quick Example:

#%RAML 1.0
title: Modern Petstore API
/pets:
  get:
    queryParameters:
      species:
        type: string
        enum: [DOG, CAT, RABBIT]
    responses:
      200:
        body:
          application/json:
            type: PetCollection

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                                                      │
│                                                                  │
│  Java/JAX-RS web services?                                      │
│  → Use WADL                                                     │
│                                                                  │
│  SOAP enterprise integration?                                   │
│  → Use WSDL                                                     │
│                                                                  │
│  API design and documentation?                                  │
│  → Use RAML                                                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

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
WADL (Java/JAX-RS Web Services): XML
WSDL (SOAP Web Services): XML
RAML 1.0 (API Design): YAML

Need help choosing? Contact us at [email protected]

Getting Started

Protocol Guides

​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)

​10. WADL (Web Application Description Language)

​11. WSDL (Web Services Description Language)

​12. RAML (RESTful API Modeling Language)

​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)

10. WADL (Web Application Description Language)

11. WSDL (Web Services Description Language)

12. RAML (RESTful API Modeling Language)

Protocol Comparison

When to Use Each Protocol

Performance Characteristics

Getting Started

For Beginners

For Specific Use Cases

Specifications

Related Resources