Faraday
Flexible HTTP client library for Ruby with a middleware stack pattern. Faraday wraps different HTTP adapters (Net::HTTP, Typhoeus, Excon, HTTParty) behind a consistent API, allowing middleware to be added for logging, authentication, retry, encoding, and response parsing. Standard choice for Ruby gems that need to make HTTP calls — most popular Ruby API client SDKs (Octokit, Stripe, Twilio) use Faraday under the hood.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
TLS by default. API keys in middleware, not URLs. SSL verification enabled by default. Net::HTTP adapter uses system CA certificates. Sensitive data in request bodies not logged by default.
⚡ Reliability
Best When
You're building a Ruby application or gem that makes HTTP API calls and want a consistent middleware pipeline for auth, logging, retry, and response parsing.
Avoid When
You need parallel HTTP requests at scale — use Typhoeus directly or async Ruby. Faraday's default Net::HTTP adapter is synchronous.
Use Cases
- • Make HTTP API calls in Ruby agent backends with configurable middleware for logging, auth token injection, and retry on failures
- • Build Ruby SDK wrappers around external APIs using Faraday as the transport layer — consistent middleware pipeline for auth, error parsing, and retries
- • Add automatic retry with exponential backoff to agent HTTP calls using faraday-retry middleware for resilient external API integration
- • Parse JSON responses automatically using faraday-encoding or custom response middleware — no manual JSON.parse calls throughout agent code
- • Switch HTTP adapters for testing — use faraday-net_http for production, stub adapter in tests to mock API responses without real HTTP calls
Not For
- • Non-Ruby projects — HTTPx (Python), Axios (JavaScript), Reqwest (Rust) for other languages
- • High-performance Ruby HTTP needs — Typhoeus (libcurl via Faraday adapter) or Curb are faster for bulk concurrent requests
- • Simple one-off HTTP requests in scripts — Net::HTTP or the 'http' gem are lighter for simple cases
Interface
Authentication
Faraday is an HTTP client — auth added via middleware. faraday-request-auth gem provides common auth patterns. Bearer token added via request.headers['Authorization'] in middleware.
Pricing
Faraday is MIT licensed. Maintained by the Lost Island team. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Faraday does NOT raise on non-2xx by default — must add faraday-raise_error middleware or check response.status; forgetting this causes silent API failures in agent code
- ⚠ Middleware order matters — request middleware runs top-to-bottom, response middleware runs bottom-to-top; adding auth middleware before logging middleware means auth headers are logged
- ⚠ Connection is not thread-safe for adapter initialization — create a new Faraday connection per thread or use a thread-safe initialization pattern; shared connections in Rails can cause adapter conflicts
- ⚠ faraday-retry 2.x changed retry_statuses to retry_on_exception — upgrading from faraday 1.x middleware to 2.x requires updating retry middleware configuration
- ⚠ Stub adapter for testing is synchronous by default — Faraday::Adapter::Test raises Faraday::Adapter::Test::Stubs::NotFound for unstubbed requests; ensure all API calls are stubbed in test mode
- ⚠ Multipart file uploads require explicit Content-Type: multipart/form-data — Faraday::UploadIO must be used with the multipart middleware; plain hash body won't trigger multipart encoding
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Faraday.
Scores are editorial opinions as of 2026-03-06.