API連携とは｜「つなぐ」は仕事の2割——残り8割は認証・上限・失敗の管理

つなぎ方は3形態——「聞きに行く・知らせてもらう・呼び合う」

即時性が要るならWebhook、確実性が要るならポーリング併用。形態の選択がその後の上限消費と失敗設計を決める。

API連携の「つなぎ方」は、突き詰めると3形態しかありません。どれを選ぶかで、後述する上限の消費量と失敗への備え方が変わります。

3形態の整理

即時性の主役はWebhook——ただし届く前提にしない

変化した瞬間に動く連携はWebhookで組みます。仕組みと受信側の設計（署名検証・重複対応）はWebhookの記事で詳しく扱っています。要点は1つ——「必ず1回だけ順番通り届く」と仮定した設計は事故るということです。

自前実装かツールか

主要SaaS同士の連携はZapier・Make・n8nのような連携ツールが最短です。ツールが認証やリトライの一部を肩代わりしますが、権限の絞り方と上限の見積もりはツールを使っても自分の仕事として残ります。次の2節がその中身です。

認証の柱——「誰の権限で、どこまで」を最初に決める

APIキーは「自分の分身」、OAuthは「限定された委任」。どちらでも原則は同じで、権限は必要最小限に絞る。

API連携の認証方式は大きく2つです。APIキーは自分のアカウントの分身となる合鍵で、発行した人の権限をそのまま持ちます。もう1つのOAuth 2.0は、他人のデータへのアクセスを、範囲を限定して委任してもらう枠組みです。

OAuthの本質は「限定されたアクセス」

OAuth 2.0の原典であるRFC 6749は、目的を冒頭でこう定義しています。“enables a third-party application to obtain limited access to an HTTP service”。鍵となる言葉はlimited（限定された）です。パスワードを渡さず、必要な範囲だけのアクセス権を切り出して渡す——「◯◯があなたのアカウントへのアクセスを求めています」という同意画面は、この委任の入口です。

実務の原則は最小権限

• 読み取りだけの連携に書き込み権限を付けない。キー漏洩時の被害範囲がそのまま権限範囲になる
• 連携ごとに別のキー・トークンを発行する。1本を使い回すと、無効化したとき全連携が止まる
• キーをコードや共有ドキュメントに直書きしない。環境変数・シークレット管理に置く

上限と失敗——連携が本番で壊れる2大要因への備え

上限は設計の入力値として最初に読む。失敗はゼロにできない前提で、リトライ・冪等性・突合の3点で受ける。

API連携が本番で壊れる原因は、コードのバグよりも「上限」と「失敗の無視」です。どちらも接続先の公式ドキュメントに対策の材料が書いてあります。

上限（レート制限）は最初に読む数字

どのAPIにも呼び出し上限があります。実例ではNotionが1接続あたり平均毎秒3リクエスト、kintoneが1アプリ1日1万リクエスト（スタンダードコース）。上限は障害ではなく仕様なので、ポーリング間隔と処理件数をこの数字から逆算して設計します。上限に優しい基本形は「定期的に全部聞く」ではなく「変化したときだけ動く」イベント駆動です。

失敗対策の3点セット

• リトライ ── 一時的な失敗は間隔を空けて再試行する。429応答は指示された待ち時間（Retry-After）に従う
• 冪等性 ── 同じ処理が2回走っても結果が変わらないように作る。再試行と重複通知の前提条件
• 突合 ── 金額が絡む連携は日次で件数・合計を照合する。取りこぼしゼロは前提にしない

そして通知——壊れたことに気づける連携だけが本番用

認証切れ・上限超過・仕様変更——どの失敗も、通知がなければ静かに止まるだけです。n8nのError Workflowのように、エラー通知の経路を連携本体より先に用意するのが、本番運用の最低条件です。