API戦略と外部連携拡張
APIを「製品」として設計するための実戦チェックリスト
APIは配管ではなく販路です。外部連携を増やすほど、運用コストと障害リスクも増えます。乱立させず、最初から「誰のための製品か」を明確にします。
- 利用者像の定義：外部パートナー、社内別チーム、マーケットプレイスの拡張開発者など。ユースケースとアンチケースを明文化します。
- 境界づけ：読み取り（クエリ）と書き込み（コマンド/イベント）を分離。状態変更は非同期イベントで返すとスケールしやすくなります。
- プロトコル選定：公開向けはREST/JSON、社内高頻度はgRPC、複合取得はGraphQLなど、目的で使い分けます。混在させる場合はガイドライン必須です。
- バージョニング：後方互換を尊重し、重大変更はv2などの経路分離。非推奨期間は6〜12カ月を目安に移行計画とツールを用意します。
- 認証・権限：サードパーティはOAuth2/OIDC、サーバ間はローテーション可能なAPIキー。スコープは最小権限、監査ログは必須です。
- リソース設計：一貫した命名、タイムゾーンはUTC、金額は通貨と精度を必ず付与。相関IDでトレース可能にします。
- レート制限と課金：アプリ単位でクォータ設定。LLM等の外部コストを考慮し、課金やフェアユースのルールを先に決めます。
LLM連携の前提整理
FAQ自動応答や分類でChatGPTやClaude、Geminiを呼び出す場合は、送信データの最小化とマスキングを標準化します。プロンプトと入出力は監査対象。モデル切替のためにプロバイダ抽象化とフォールバック戦略（例：Claudeが失敗したらChatGPTへ）を実装します。
外部連携をスケールさせる技術設計
- Webhookは製品品質で：シグネチャ検証、再送（指数バックオフ）、順序保証、重複排除のためのidempotency-keyを実装します。
- 変更のみ取得：ポーリングを避け、イベント駆動＋deltaクエリやsinceパラメータで差分取得。大量データはカーソル型ページングに統一します。
- カノニカルデータモデル：外部ごとの差異はアダプタ層で吸収。検証はスキーマで自動化し、変換エラーを可観測化します。
- 可観測性：全リクエストに相関ID、構造化ログ、分散トレース。主要メトリクスはp95レイテンシ、成功率、レートリミット到達数、外部依存のエラー率です。
- 回路遮断とリトライ：外部API障害時は即座にフォールバック（キャッシュ、遅延キュー、別プロバイダ）へ。SLAに応じたタイムアウトを設計します。
セキュリティとデータ保護
PIIは原則送らない、送る場合はDLPでマスク。保管しない方針ならログに残さない。キーやシークレットは自動ローテーション、アクセスはゼロトラスト前提で最小化します。
身近な企業活用例：失敗からのやり直し
地方で20店舗を運営する中堅小売。EC拡張で在庫、決済、配送、マーケの外部連携を「とりあえず」直結。セール時にWebhookが雪崩的に到来し、重複注文と在庫乖離が多発。開発は属人的、仕様変更のたびに連鎖障害が発生していました。
改善では、まず受け口を統一する公開APIを新設。注文作成はidempotency-key必須化、在庫は更新イベントを非同期に配信。Webhookは署名検証とバックオフを導入し、順序制御のためのメッセージキューを挟みました。外部差分はアダプタ層で吸収し、商品・価格・在庫のカノニカルスキーマを定義。LLMは商品説明の要約とカテゴリ補完に限定し、Geminiで分類、失敗時はClaude、最終フォールバックでChatGPTという順に切替。FAQボットは営業時間外のみ応答、個人情報はマスクして送信。可観測性では相関IDを全経路に付与、p95レイテンシが目標を超えると自動でフォールバックが有効化される仕組みにしました。
結果、障害対応時間は半減、セール時の重複注文はゼロに。新規連携のリードタイムも3週間から1週間へ短縮。開発チームはCopilotの補助でスキーマやテストの整備を平準化し、仕様逸脱の検出を自動化できました。ポイントは「APIを1本化し、外部差分はアダプタで吸収」「非同期と再送・重複排除を前提にする」「LLMは目的を絞りデータを最小化」の3つでした。
運用ルールと契約設計で価値を積み上げる
- SLO/SLA：可用性、p95レイテンシ、エラー率、Webhook遅延など、計測可能な指標に限定。エラーバジェットでリリース頻度と安定性のバランスを取ります。
- 公開ドキュメント：例外仕様、レート制限、ステータスコード、非推奨ポリシー、移行ガイド。サンプルはテスト可能な形で提供します。
- リスク分離：テナント分離、キュー分離、プロバイダごとの回路遮断。高優先ジョブと通常ジョブをキューで分流。
- ライフサイクル管理：スキーマ変更は互換性チェックをCIに組込み、デプロイは段階ロールアウト。鍵と証明書の期限は自動アラート。
- データ契約：外部ベンダーとはデータ最小化と保持期間、再委託の可否、削除SLAを明記。LLM利用時の再学習有無も合意しておきます。
API戦略は「何とつながるか」だけでなく、「どこで差別化し、どこを外部に任せるか」の設計です。生成AIの活用も、ChatGPT・Claude・Geminiを役割分担させれば、コストと品質のバランスを取りやすくなります。受託開発ソリューション事業では、要件定義からアーキテクチャ設計、アダプタ実装、運用規約策定、監視設計までを一貫して整え、外部連携を“増やせば増やすほど強くなる”状態へ育てます。
