hatch-surf/examples/README.md

Hatch Examples

Real-world examples and integration guides for using Hatch.

Examples Index

Example	Description	Use Case
Webhook Integration	Comprehensive webhook capture, testing, and debugging	Payment processors, GitHub, Slack, API integrations

Quick Start Examples

Capture Your First Request

# Start Hatch server
hatch serve &

# Capture a request
curl -X POST http://localhost:8080/my-endpoint \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"id":123}}'

# View captured requests
hatch inspect my-endpoint

Mock API for Development

# Configure mock response
hatch mock set api/users \
  -status 200 \
  -header "Content-Type:application/json" \
  -body '[{"id":1,"name":"John Doe"}]'

# Test your frontend
curl http://localhost:8080/api/users

Debug Failed Webhooks

# Find errors
hatch search webhooks -query "status:500"

# Replay to debug
hatch replay <request-id> \
  -endpoint webhooks \
  -target http://localhost:3000/debug

Integration Guides

Stripe Webhooks

See Webhook Integration - Stripe Example

GitHub Webhooks

See Webhook Integration - GitHub Example

Slack Integration

See Webhook Integration - Slack Example

Use Cases

1. Development Environment

Use Hatch as a local mock server for frontend development.

# Configure mocks for your API
hatch mock set api/users -status 200 -body '[]'
hatch mock set api/auth -status 200 -body '{"token":"mock-token"}'

# Frontend code uses http://localhost:8080 as API base

2. Testing & QA

Capture production traffic patterns and replay them in testing.

# Capture traffic
hatch inspect api/critical-path -limit 1000 > traffic.json

# Replay in test environment
cat traffic.json | jq -r '.[].id' | while read id; do
  hatch replay "$id" -endpoint api/critical-path -target http://staging:8080
done

3. API Documentation

Generate OpenAPI specs from real traffic.

# Capture representative traffic
hatch capture /api/users -method GET
hatch capture /api/users -method POST -body '{"name":"test"}'

# Generate documentation
hatch doc generate api/users > users-api.json

4. Load Testing

Replay captured traffic for load testing.

# Capture production patterns
hatch inspect api/critical-path -limit 1000 > load-test-traffic.json

# Create load test script
cat > load-test.sh << 'EOF'
#!/bin/bash
for i in {1..100}; do
  hatch inspect api/critical-path -limit 10 | \
    jq -r '.[] | "hatch replay \(.id) -endpoint api/critical-path -target http://loadtest:8080"' | \
    bash &
done
wait
EOF
chmod +x load-test.sh

Best Practices

1. Use descriptive endpoint names

   # Good
   hatch capture /webhooks/stripe-payments
   hatch capture /api/v2/users
   
   # Bad
   hatch capture /a
   hatch capture /test
   

2. Include relevant headers

   hatch capture /webhooks/github \
     -header 'X-GitHub-Event:push' \
     -header 'X-Hub-Signature:sha1=abc123'
   

3. Organize by environment

   # Development
   hatch mock set dev/api/users -status 200 -body '[]'
   
   # Staging
   hatch mock set staging/api/users -status 200 -body '[{"id":1}]'
   

4. Use search for debugging

   # Find all errors
   hatch search api/webhooks -query 'status:500'
   
   # Find specific events
   hatch search webhooks/stripe -query 'payment_intent'
   

Troubleshooting

See CLI Troubleshooting Guide for common issues and solutions.

Contributing Examples

To add a new example:

1. Create a markdown file in this directory
2. Follow the naming convention: <use-case>.md
3. Include:
   • Clear use case description
   • Step-by-step instructions
   • Complete code examples
   • Expected output
   • Common pitfalls
4. Update this README.md to include your example in the index

Resources

• CLI Reference - Complete command documentation
• Quick Reference - Command cheat sheet
• Troubleshooting - Common issues and solutions