external-api-integration

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

# app/clients/hubspot_client.rb
class HubspotClient
  def initialize
    @conn = Faraday.new(url: "https://api.hubapi.com") do |f|
      f.request :json
      f.request :authorization, "Bearer", -> { Rails.application.credentials.hubspot_api_key }
      f.request :retry, max: 3, interval: 0.5, backoff_factor: 2,
                         retry_statuses: [429, 500, 502, 503, 504],
                         methods: %i[get put]  # idempotent verbs only
      f.response :raise_error  # raise on 4xx/5xx
      f.response :json
      f.response :logger, Rails.logger, headers: false, log_level: :info do |log|
        log.filter(/(Authorization: Bearer )(\S+)/i, '\1[FILTERED]')
      end
      f.options.open_timeout = 3
      f.options.timeout = 10
      f.adapter Faraday.default_adapter
    end
  end

  def upsert_contact(email:, attrs:)
    Stoplight("hubspot.upsert_contact") do
      @conn.post("/contacts/v1/contact/createOrUpdate/email/#{email}", { properties: attrs.map { |k, v| { property: k, value: v } } }).body
    end.with_threshold(5).with_cool_off_time(60).run
  end
end

Why every piece:

• request :retry — handles transient failures without app-level code.
• retry_statuses: [429, 500, ...] — only retry on transient failures, not on 401/422.
• methods: %i[get put] — only retry idempotent operations. Don't auto-retry POST (might double-create).
• response :raise_error — turn 4xx/5xx into exceptions; cleaner control flow.
• response :logger with sanitization — visibility without leaking creds.
• Timeouts — never hang on a flaky upstream.
• Stoplight circuit breaker — after 5 failures in window, requests fail fast for 60s.