外部API連携の設計と運用 — 認証・レート制限・仕様変更への備え

決済、地図、メッセージ配信、本人確認、生成AI。現代のWebサービスは、多くの機能を外部のAPI（他社のシステムの機能やデータを利用するための接続口）に頼って成り立っています。自社で作る範囲を減らし、早く高品質な機能を提供できる一方で、外部APIは自社で制御できない存在でもあります。

本記事では、外部API連携を「つないで終わり」にしないために、認証、レート制限とリトライ、冪等性、仕様変更や障害への備え、ログと監視、利用規約の確認といった設計と運用の要点を整理します。技術者ではない事業責任者が、開発チームや開発パートナーと会話するための土台としてご活用ください。

APIの基本と認証方式の考え方

APIは、自社のシステムから外部のシステムへ「この処理をしてほしい」「このデータがほしい」と依頼し、結果を受け取る仕組みです。依頼する側は、自分が誰であるかを証明する必要があり、そのための仕組みが認証です。

代表的な考え方は次の通りです。

どの方式でも共通するのは、鍵やトークンをソースコードに直接書かず、環境ごとに分離して安全に保管すること、そして漏えいや退職者の発生時に無効化・再発行できる手順を持っておくことです。

レート制限とリトライ・バックオフ

外部APIの多くは、一定時間に受け付ける依頼の数に上限を設けています。これがレート制限です。上限を超えると依頼は拒否され、繰り返すとアカウントごと制限されることもあります。

対応の基本は次の三つです。

• 上限を把握し、自社の利用量が上限に近づいたら検知できるようにする
• 失敗したときは、すぐに再試行せず、間隔を徐々に広げながら再試行する（バックオフ）
• 再試行の回数に上限を設け、それでも失敗した場合の扱いを決めておく

想定例：予約確定のたびに宿泊者へメッセージを送るサービスで、繁忙期に予約が集中し、配信APIの上限を超えてしまうとします。バックオフなしで再試行を繰り返すと、上限超えが続いて全員に届かなくなります。送信をいったんキューに入れ、上限に収まる速さで順に送る設計なら、遅れはあっても確実に届きます。

冪等性：再試行しても結果が変わらない設計

再試行を安全に行うには、冪等性（べきとうせい）という性質が必要です。同じ依頼を何度送っても、結果が一度送った場合と同じになることを指します。

典型的な問題は決済です。「支払いを実行する」依頼を送った直後に通信が切れ、成功したかどうか分からない状態で再試行すると、二重に課金される恐れがあります。これを防ぐため、多くの決済APIは依頼ごとに一意の識別子を付ける仕組みを用意しており、同じ識別子の依頼は一度しか処理されません。

自社側でも、依頼に一意の識別子を付け、送信前に記録し、結果を受け取ったら記録を更新する、という手順を設計します。これにより「送ったか分からない」状態を減らし、安全な再試行が可能になります。

仕様変更・廃止への備え

外部APIは、提供元の都合で仕様が変わり、ときには提供そのものが終了します。これを前提とした設計が必要です。

• バージョンの明示: 呼び出すAPIのバージョンを固定し、新バージョンへの移行を計画的に行う
• 告知の受け取り: 提供元の開発者向けの通知やお知らせを受け取る担当と経路を決める
• 抽象化層: 外部APIを直接呼ぶ処理を一か所にまとめ、他の部分はその内側だけを使う。提供元を切り替える場合も影響を限定できる
• 廃止時の代替案: 同種の機能を提供する別のサービスを把握しておく

抽象化層を設けずにアプリケーションの各所から外部APIを直接呼んでいると、仕様変更のたびに広範囲の修正が必要になり、技術的負債として積み上がります。最初に一手間かけておく価値のある部分です。

障害時の振る舞い：フォールバックとキュー

外部APIは、自社に落ち度がなくても止まります。そのとき自社サービスがどう振る舞うかを、機能ごとに決めておきます。

• フォールバック: 地図が表示できなければ住所だけ表示する、おすすめが取れなければ人気順を表示するなど、劣化した状態でも使えるようにする
• キュー: メッセージ送信や集計など即時性が不要な処理は、いったん貯めて復旧後に実行する
• タイムアウト: 応答を待ち続けて自社サービス全体が遅くならないよう、待ち時間の上限を設ける
• 遮断: 連続して失敗している間は呼び出しを一時的に止め、復旧を確認してから再開する

想定例：ECサイトで、配送日の候補を外部APIから取得しているとします。APIが止まった場合に注文自体を受け付けられなくするか、「配送日は後日ご案内」として注文は受けるかで、機会損失の大きさは変わります。事業上の優先度に基づいて、どこまで劣化を許容するかを決めておきます。

ログ・監視と利用規約の確認

運用が始まってからの安定性は、ログと監視で支えます。

• 依頼と応答の記録: 何を送り、何が返ったかを記録する。ただし個人情報や認証情報は記録から除く
• 失敗率と応答時間の監視: 平常時との差を検知し、提供元の障害や自社側の不具合を早く見つける
• 利用量の可視化: レート制限や課金の上限に対して、現在どの程度使っているかを把握する

また、技術面と同じくらい重要なのが利用規約の確認です。取得したデータを自社で保存してよいか、他の目的に使ってよいか、商用利用に制限はないか、提供元のロゴ表示が必要かなど、条件はサービスごとに異なります。特に個人情報を含むデータや、生成AIのAPIに送る内容については、規約と自社のプライバシーポリシーの整合を確認しておく必要があります。

制御できない相手を前提に設計する

外部API連携は、自社で制御できない相手と協調する設計です。認証情報の安全な管理、レート制限を踏まえたリトライとバックオフ、冪等性による安全な再試行、抽象化層と監視による仕様変更への備え、フォールバックとキューによる障害時の振る舞い、そして利用規約の確認。これらを最初から織り込んでおくことで、連携先の事情に振り回されない安定したサービスになります。

フィリット・コンサルティングでは、Webシステム開発とサーバーインフラ整備を通じて、外部API連携の設計から監視体制の構築までを支援しています。連携先の選定や既存の連携の見直しでお困りの方は、お問い合わせからご相談ください。