External API Integration

Calling external APIs is where Rails apps lose reliability. AI agents reach for Net::HTTP.get(URI(url)), no timeouts, no retries, no logging, no circuit breaker. Replace with Faraday + middleware + service object wrapper.

The opinion

Faraday for the HTTP client. Wrap every external API in a service object. Open timeout 3s, read timeout 10s (tune per API). Exponential retries (3 attempts) on idempotent verbs. Circuit breaker for chronically-flaky upstreams. VCR for tests. Log every call (sanitized) with correlation IDs. Idempotency keys on writes when the API supports them. Never put external calls in the request path if you can help it — use a job.

Core patterns

Pattern 1: The Faraday client wrapper

# Gemfile
gem "faraday"
gem "faraday-retry"
gem "stoplight"  # circuit breaker