APIはCloudflare Workers上のHonoで構築されており、低レイテンシーとグローバル分散のために最適化されています。ここでは構築と保守の方法を説明します。
Honoフレームワーク
軽量フットプリントとエッジファーストの設計でHonoを選択しました：
- 小さなバンドル： HonoはWorkerのサイズへのオーバーヘッドが最小限で、コールドスタートを高速に保ちます。
- 慣れ親しんだパターン： Expressライクなルーティングでデベロッパーのオンボーディングを容易にします。
- 組み込みミドルウェア： CORS、圧縮、ロギングが即座に機能します。
- 型安全性： リクエスト/レスポンスの型付けを持つ完全なTypeScriptサポート。
エッジファーストの設計
すべてのAPI決定はエッジデプロイの制約を考慮します：
- ステートレスハンドラー： リクエスト間でサーバーサイドセッションやローカルストレージはありません。
- 外部状態： すべての状態はSupabase（SQL）、Cloudflare KV（キーバリュー）、R2（ブロブ）に存在します。
- コールドスタートの最適化： 必要な時だけ重いクライアント（Stripe、Supabase）の遅延初期化。
- リージョナルルーティング： Cloudflareが自動的にリクエストを最寄りのエッジロケーションにルーティングします。
リクエストバリデーション
Zodがすべての受信データにランタイム型安全性を提供します：
- スキーマ定義： すべてのエンドポイントがZodスキーマで期待される入力形状を定義します。
- 自動パース： 無効なリクエストは明確なエラーメッセージと共に素早く失敗します。
- 型推論： TypeScriptの型はスキーマから導出され、一貫性を確保します。
- 変換： Zodが型変換（文字列から数値へ）とデフォルト値をクリーンに処理します。
エラーハンドリング
一貫したエラーレスポンスでデバッグを容易にします：
- 構造化フォーマット： すべてのエラーはerror、message、オプションのdetailsを持つJSONを返します。
- HTTPステータスコード： 適切なコードを使用します（バリデーションには400、認証には401、権限には403、レート制限には429）。
- エラートラッキング： 例外はデバッグのためにリクエストコンテキストと共にログされます。
- ユーザーフレンドリーなメッセージ： 技術的な詳細はログされますが、クライアントには公開されません。
レート制限
公平さを保ちながらシステムを保護するレート制限戦略：
- 段階的な制限： トラッキングエンドポイント（高）、APIエンドポイント（中）、認証エンドポイント（低）に異なる制限。
- キーごとの追跡： APIキーはサブスクリプションティアに基づいた個別クォータを持ちます。
- スライディングウィンドウ： 制限は固定期間ではなく、ローリングタイムウィンドウで計算されます。
- グレースフルデグラデーション： レート制限されたリクエストはRetry-Afterヘッダーを受け取ります。
エンドポイントの組織
ルートは保守性のためにドメインごとに整理されています：
- /e/:trackingCode — パブリックトラッキング（広告ブロッカーフレンドリー）
- /api/analytics/* — ダッシュボードデータクエリ
- /api/replay/* — セッションリプレイ管理
- /api/billing/* — Stripe統合
- /api/team/:teamId/* — チームスコープの操作
- /api/external/v1/* — サードパーティAPIアクセス
- /api/cron/* — スケジュールタスクのトリガー（Webhook認証）