API インテグレーション — 顧客システムとの接続点を設計する

# app/services/ai_provider/base.rb
module AiProvider
  class Base
    def initialize(api_key:, endpoint:)
      @api_key = api_key
      @endpoint = endpoint
    end
 
    def predict(input)    = raise NotImplementedError
    def health_check      = raise NotImplementedError
    def batch_predict(inputs) = inputs.map { |input| predict(input) }
 
    private
 
    def with_retry(max_attempts: 3)
      attempts = 0
      begin
        attempts += 1
        yield
      rescue StandardError => e
        raise if attempts >= max_attempts
        sleep((2**attempts) + rand(0.0..1.0))
        retry
      end
    end
  end
end

# app/services/ai_provider/arclight.rb
module AiProvider
  class Arclight < Base
    def predict(input)
      with_retry do
        response = connection.post("/v2/predict") do |req|
          req.headers["Authorization"] = "Bearer #{@api_key}"
          req.body = { input: input, model: "arclight-v3" }.to_json
        end
 
        raise AiProvider::Error, "API error: #{response.status}" unless response.success?
        body = response.body
        AiProvider::Result.new(prediction: body["prediction"],
          confidence: body["confidence"], model_version: body["model_version"])
      end
    end
 
    def health_check
      connection.get("/health").status == 200
    end
 
    private
 
    def connection
      @connection ||= Faraday.new(url: @endpoint) do |f|
        f.request :json
        f.response :json
        f.adapter Faraday.default_adapter
        f.options.timeout = 30
      end
    end
  end
end
 
# app/services/ai_provider/registry.rb
module AiProvider
  class Registry
    PROVIDERS = {
      arclight: AiProvider::Arclight,
      openai: AiProvider::OpenAi,
      anthropic: AiProvider::Anthropic
    }.freeze
 
    def self.resolve(provider_name)
      klass = PROVIDERS.fetch(provider_name.to_sym) do
        raise ArgumentError, "未対応プロバイダ: #{provider_name}"
      end
 
      config = Rails.application.credentials.ai_providers[provider_name.to_sym]
      klass.new(api_key: config[:api_key], endpoint: config[:endpoint])
    end
  end
end

# config/initializers/omniauth.rb
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :saml,
    issuer: "https://arclight.ai",
    idp_sso_service_url: ENV.fetch("NEXTERA_IDP_SSO_URL"),
    idp_cert_fingerprint: ENV.fetch("NEXTERA_IDP_CERT_FINGERPRINT"),
    name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
end

# app/services/oauth_token_manager.rb
class OauthTokenManager
  TOKEN_EXPIRY_BUFFER = 60.seconds
 
  def initialize(integration:)
    @integration = integration
  end
 
  def valid_access_token
    refresh_token! if token_expired?
    @integration.access_token
  end
 
  private
 
  def token_expired?
    @integration.token_expires_at <= Time.current + TOKEN_EXPIRY_BUFFER
  end
 
  def refresh_token!
    response = Faraday.post(@integration.token_endpoint) do |req|
      req.body = {
        grant_type: "refresh_token",
        refresh_token: @integration.refresh_token,
        client_id: @integration.client_id,
        client_secret: @integration.client_secret
      }
    end
 
    body = JSON.parse(response.body)
    @integration.update!(
      access_token: body["access_token"],
      refresh_token: body["refresh_token"],
      token_expires_at: Time.current + body["expires_in"].seconds
    )
  rescue Faraday::Error => e
    raise OauthTokenManager::RefreshError, "トークン更新に失敗: #{e.message}"
  end
end

# app/services/rate_limiter.rb
# Redis + Lua スクリプトによるトークンバケット実装
class RateLimiter
  def initialize(key:, max_tokens:, refill_rate:)
    @key = "rate_limit:#{key}"
    @max_tokens = max_tokens
    @refill_rate = refill_rate # tokens per second
  end
 
  def acquire!(tokens: 1)
    allowed = Redis.current.eval(TOKEN_BUCKET_LUA, keys: [@key],
      argv: [@max_tokens, @refill_rate, tokens, Time.current.to_f])
    raise RateLimitExceeded, "レート制限超過: #{@key}" unless allowed == 1
  end
 
  # Lua スクリプト: 経過時間でトークンを補充し、要求分を消費
  TOKEN_BUCKET_LUA = <<~LUA
    local key, max, rate = KEYS[1], tonumber(ARGV[1]), tonumber(ARGV[2])
    local requested, now = tonumber(ARGV[3]), tonumber(ARGV[4])
    local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
    local tokens = tonumber(bucket[1]) or max
    local last = tonumber(bucket[2]) or now
    tokens = math.min(max, tokens + (now - last) * rate)
    if tokens >= requested then
      redis.call('HMSET', key, 'tokens', tokens - requested, 'last_refill', now)
      redis.call('EXPIRE', key, 300)
      return 1
    end
    return 0
  LUA
end

# app/services/resilient_api_client.rb
class ResilientApiClient
  MAX_RETRIES = 5
  BASE_DELAY = 0.5
  MAX_DELAY = 30.0
 
  def initialize(base_url:, rate_limiter:)
    @base_url = base_url
    @rate_limiter = rate_limiter
  end
 
  def request(method:, path:, body: nil)
    retries = 0
    begin
      @rate_limiter.acquire!
      response = connection.public_send(method, path) { |req| req.body = body.to_json if body }
      handle_response(response)
    rescue RateLimitExceeded, Faraday::TooManyRequestsError, Faraday::ServerError => e
      retries += 1
      raise if retries > MAX_RETRIES
      sleep(calculate_backoff(retries))
      retry
    end
  end
 
  private
 
  # Exponential Backoff with Full Jitter
  # delay = random(0, min(cap, base * 2^attempt))
  def calculate_backoff(attempt)
    max_delay_for_attempt = [MAX_DELAY, BASE_DELAY * (2**attempt)].min
    rand(0.0..max_delay_for_attempt)
  end
 
  def handle_response(response)
    case response.status
    when 200..299 then response.body
    when 429 then raise Faraday::TooManyRequestsError, "Rate limited"
    when 500..599 then raise Faraday::ServerError, "Server error: #{response.status}"
    else raise ApiError, "Unexpected status: #{response.status}"
    end
  end
end

# app/controllers/api/base_controller.rb
module Api
  class BaseController < ApplicationController
    before_action :determine_api_version
    SUPPORTED_VERSIONS = [1, 2, 3].freeze
    SUNSET_DATES = { 1 => "Sat, 31 Dec 2026 23:59:59 GMT" }.freeze
 
    private
 
    def determine_api_version
      @api_version = extract_version
      render json: { error: "Unsupported API version" }, status: :not_acceptable unless SUPPORTED_VERSIONS.include?(@api_version)
    end
 
    def extract_version
      # URL パス (/api/v2/...) → Accept ヘッダー → デフォルト v2
      if (m = request.path.match(%r{/api/v(\d+)/})) then m[1].to_i
      elsif (m = request.headers["Accept"]&.match(/vnd\.arclight\.v(\d+)/)) then m[1].to_i
      else 2
      end
    end
 
    # RFC 8594 Sunset ヘッダーで廃止予定を通知
    def set_sunset_header(version)
      if (date = SUNSET_DATES[version])
        response.headers["Sunset"] = date
        response.headers["Deprecation"] = "true"
        response.headers["Link"] = '</api/v2/>; rel="successor-version"'
      end
    end
  end
end

# app/controllers/api/v1/predictions_controller.rb
module Api
  module V1
    class PredictionsController < Api::BaseController
      before_action -> { set_sunset_header(1) }
 
      def create
        result = prediction_service.predict(prediction_params)
        # v1: フラットなレスポンス（レガシー）
        render json: { result: result.prediction, score: result.confidence }
      end
    end
  end
end
 
# app/controllers/api/v2/predictions_controller.rb
module Api
  module V2
    class PredictionsController < Api::BaseController
      def create
        result = prediction_service.predict(prediction_params)
        # v2: JSON:API 風の構造化レスポンス
        render json: {
          data: {
            type: "prediction", id: result.id,
            attributes: {
              prediction: result.prediction,
              confidence: result.confidence,
              model_version: result.model_version
            }
          },
          meta: { api_version: 2, request_id: request.request_id }
        }
      end
    end
  end
end

# app/models/webhook_event.rb
class WebhookEvent < ApplicationRecord
  belongs_to :integration
 
  enum :status, { pending: "pending", delivering: "delivering",
                  delivered: "delivered", failed: "failed", dead_letter: "dead_letter" }
 
  MAX_ATTEMPTS = 8
 
  scope :retryable, -> {
    where(status: [:pending, :failed]).where("attempts < ?", MAX_ATTEMPTS)
      .where("next_retry_at <= ?", Time.current)
  }
 
  def schedule_retry!
    delay = (2**attempts) + rand(0.0..1.0)  # 指数バックオフ + ジッター
    update!(status: :failed, next_retry_at: Time.current + delay.seconds)
  end
 
  def mark_dead_letter!
    update!(status: :dead_letter)
    WebhookDeadLetterNotifier.notify(self)
  end
end

# app/services/webhook_delivery_service.rb
class WebhookDeliveryService
  def deliver(event)
    event.update!(status: :delivering, attempts: event.attempts + 1)
    response = send_webhook(event)
 
    if response.success?
      event.update!(status: :delivered, delivered_at: Time.current)
    else
      handle_failure(event, "HTTP #{response.status}")
    end
  rescue Faraday::Error => e
    handle_failure(event, e.message)
  end
 
  private
 
  def send_webhook(event)
    timestamp = Time.current.to_i.to_s
    payload = "#{timestamp}.#{event.payload.to_json}"
    signature = OpenSSL::HMAC.hexdigest("SHA256", event.integration.webhook_secret, payload)
 
    Faraday.post(event.integration.webhook_url) do |req|
      req.headers["Content-Type"] = "application/json"
      req.headers["X-Arclight-Signature"] = signature
      req.headers["X-Arclight-Timestamp"] = timestamp
      req.headers["X-Idempotency-Key"] = event.idempotency_key
      req.body = event.payload.to_json
      req.options.timeout = 10
    end
  end
 
  def handle_failure(event, error_message)
    event.update!(last_error: error_message)
    event.attempts >= WebhookEvent::MAX_ATTEMPTS ? event.mark_dead_letter! : event.schedule_retry!
  end
end

# app/controllers/api/v2/webhooks_controller.rb（受信側）
module Api
  module V2
    class WebhooksController < Api::BaseController
      skip_before_action :verify_authenticity_token
 
      def receive
        return render json: { error: "Invalid signature" }, status: :unauthorized unless valid_signature?
 
        idempotency_key = request.headers["X-Idempotency-Key"]
        return render json: { status: "already_processed" } if ProcessedWebhook.exists?(idempotency_key:)
 
        ActiveRecord::Base.transaction do
          ProcessedWebhook.create!(idempotency_key:)
          WebhookProcessorJob.perform_later(params[:event_type], params[:data].to_json)
        end
        render json: { status: "accepted" }, status: :accepted
      end
 
      private
 
      def valid_signature?
        payload = "#{request.headers['X-Arclight-Timestamp']}.#{request.raw_post}"
        expected = OpenSSL::HMAC.hexdigest("SHA256", webhook_secret, payload)
        ActiveSupport::SecurityUtils.secure_compare(request.headers["X-Arclight-Signature"], expected)
      end
    end
  end
end

# app/services/circuit_breaker.rb
class CircuitBreaker
  def initialize(service_name:, failure_threshold: 5, reset_timeout: 30, half_open_max: 3)
    @service_name = service_name
    @failure_threshold = failure_threshold
    @reset_timeout = reset_timeout
    @half_open_max = half_open_max
    @state = :closed
    @failure_count = 0
    @last_failure_at = nil
    @half_open_successes = 0
    @mutex = Mutex.new
  end
 
  def call(&block)
    check_state!
 
    begin
      result = yield
      record_success
      result
    rescue StandardError => e
      record_failure
      raise
    end
  end
 
  private
 
  def check_state!
    @mutex.synchronize do
      if @state == :open
        if Time.current - @last_failure_at >= @reset_timeout
          transition_to(:half_open)
        else
          raise CircuitOpenError, "Circuit open for #{@service_name}"
        end
      end
    end
  end
 
  def record_success
    @mutex.synchronize do
      if @state == :half_open
        @half_open_successes += 1
        transition_to(:closed) if @half_open_successes >= @half_open_max
      end
      @failure_count = 0
    end
  end
 
  def record_failure
    @mutex.synchronize do
      @failure_count += 1
      @last_failure_at = Time.current
      transition_to(:open) if @failure_count >= @failure_threshold || @state == :half_open
    end
  end
 
  def transition_to(new_state)
    Rails.logger.info("[CircuitBreaker] #{@service_name}: #{@state} -> #{new_state}")
    @state = new_state
    @failure_count = 0 if new_state == :closed
    @half_open_successes = 0 if new_state == :half_open
  end
end

# 使用例: サーキットブレーカー + レート制限 + フォールバック
class NexteraApiClient
  def initialize
    @circuit = CircuitBreaker.new(service_name: "nextera_api", failure_threshold: 5, reset_timeout: 30)
    @rate_limiter = RateLimiter.new(key: "nextera", max_tokens: 600, refill_rate: 10)
  end
 
  def fetch_transactions(account_id:, from:, to:)
    @circuit.call do
      @rate_limiter.acquire!
      connection.get("/api/v2/accounts/#{account_id}/transactions",
        from: from.iso8601, to: to.iso8601)
    end
  rescue CircuitOpenError
    CachedTransactions.latest(account_id:) # フォールバック: キャッシュデータ
  end
end

# app/jobs/webhook_delivery_job.rb
class WebhookDeliveryJob < ApplicationJob
  queue_as :webhooks
  retry_on StandardError, wait: :polynomially_longer, attempts: 8
 
  def perform(webhook_event_id)
    event = WebhookEvent.find(webhook_event_id)
    WebhookDeliveryService.new.deliver(event) unless event.delivered?
  end
end