変更要約: 初版
2.3API利用パターンと制約
イベント発生時にサーバからクライアントへ通知を送るWebhook（ポーリングの逆呼び出し）と、API消費時に必ず直面する制約——単位時間あたりの呼び出しを制限するレート制限（429・Retry-After・指数バックオフ）と、大量データを分割して返すページネーション（limit/offset・カーソル・nextリンク）——を、「この要件にはポーリングかWebhookか」「この429や途切れたデータをどう扱うか」という判断・診断として学びます。
APIは「呼べば即・全部返ってくる」理想的な窓口ではありません。実運用では、変化をどう知るか（ポーリング対Webhook）、呼びすぎをどう抑えるか（レート制限）、大量データをどう分割して取るか（ページネーション）という3つの制約に必ず突き当たります。これらを知らないと、無駄なポーリングでレート制限に引っかかり（429）、1ページ目だけ見て「データが足りない」と誤解します。この節では、各制約の意味とそれに合わせた正しい設計/対処を判断型で学びます。
2.3.1Webhookとポーリング
- ポーリング＝クライアントが「もう変わった？」と定期的にAPIを叩いて状態を確認する方式。実装は簡単だが、変化が稀だと大半が空振りで、頻度を上げるほどレート制限に近づく。「最新の変化を1分以内に知りたい」だけのために毎秒叩くのは非効率。
- Webhook＝イベントが起きたときに、サーバがクライアントの登録済みURLへHTTP POSTで通知を送りつける逆方向の呼び出し。クライアントは受け口（コールバックURL）を用意して待つだけでよく、変化を即時・低負荷で受け取れる。「アラートが発生した瞬間に通知したい」「稀な状態変化を待ち受けたい」ならポーリングよりWebhookが適する。
- 使い分けの判断軸は変化の頻度・即時性の要求・受け口を公開できるか。Webhookは受信用の到達可能なエンドポイントが要り、届いた通知の真正性検証（署名）や重複/順不同への配慮が必要。一方、単発の一覧取得や同期的な問い合わせは素直にポーリング（リクエスト/レスポンス）でよい。
2.3.2レート制限とページネーション
- レート制限＝単位時間あたりの呼び出し回数の上限。超えると
429 Too Many Requestsが返り、多くはRetry-After（待機秒数）やX-RateLimit-Remaining（残回数）ヘッダが付く。正しい対処は指示に従って待ち、以降は指数バックオフ（失敗ごとに待機を倍々に延ばす）で頻度を落とすこと。リトライを詰めるのは逆効果。 - ページネーション＝大量の結果を複数ページに分割して返す仕組み。
?limit=100&offset=200のようなoffset方式、直前ページ末尾を指すカーソル方式、応答にnextリンクを含める方式などがある。1ページ目だけ取得して全件と誤解しないのが要点で、nextが無い（または返件数がlimit未満）まで繰り返し取得して初めて全件になる。
「稀な変化・即時通知はWebhook（サーバ→クライアントの逆POST）／単発取得はポーリング」「429はRetry-Afterに従い指数バックオフ」「大量データはページネーション＝nextが尽きるまで繰り返し取得（1ページ目＝全件ではない）」が頻出です。設問は「無駄なポーリングをやめてWebhookにすべきか」「この429や途切れたデータへの正しい一手は何か」で解きましょう。
あなたはネットワーク監視ツールを作っており、「機器のアラートが発生したら即座に担当者へ知らせる」機能を実装します。最初の実装は、アラートAPIを5秒ごとにポーリングして新規アラートが無いか確認するものでした。稼働させるとすぐ429 Too Many Requestsが頻発し、Retry-After: 30が返ります。ここで「待機を無くして間隔をもっと詰めれば取りこぼさない」と考えるのは完全な逆効果で、レート制限をさらに叩いて429が悪化するだけです。正しい判断は二段構えです。まず短期的には、Retry-Afterに従って待ち、ポーリングを指数バックオフ（失敗するたび待機を30秒→60秒→120秒…と延ばす）に変えて呼び出し頻度を制限内に収めます。しかし本質的には、この用途はポーリングが構造的に不向きです——アラートは稀にしか起きないのに、即時性のために高頻度で空振りを繰り返すからです。docsを見るとこのAPIはWebhookに対応しており、アラート発生時にこちらの登録URLへPOST通知を送れます。そこで設計を切り替え、コールバックURLを用意してWebhookを登録すれば、アラートが起きた瞬間だけ通知が届き、ポーリングの空振りもレート制限の問題も同時に解消します。さらに、機器一覧のような大量データを別途取得する処理では、GET /devices?limit=100がnextリンク付きで返るので、nextが無くなるまで繰り返し取得しなければ全機器を網羅できません（1ページ目だけ見て「100台しかない」と誤解しない）。ここで学ぶべきは、429という症状は「待機を消す」で押し切るものではなく、制約（レート制限・ポーリングの非効率・ページ分割）の性質に設計を合わせる——即時通知はWebhook、頻度はバックオフ、全件取得はページ反復——という判断だ、ということです。
| 制約/パターン | 症状/兆候 | 正しい一手 |
|---|---|---|
| ポーリングの非効率 | 稀な変化のために高頻度で空振り | Webhook（サーバ→クライアントの逆POST）に切替 |
| レート制限 | `429 Too Many Requests`＋`Retry-After` | 指示秒数待機→指数バックオフで頻度を下げる |
| ページネーション | 1ページ分しか返らない／`next`リンク付き | `next`が尽きるまで繰り返し取得して全件化 |
ひっかけ： 「429が出るのは待機のせいだから、Retry-Afterを無視して間隔を詰めれば取りこぼさない」は誤りです——レート制限は頻度そのものへの制限なので、詰めるほど429が悪化します。正しくは待機＋指数バックオフ、可能ならWebhook化です。また「一覧APIの1ページ目に載っていない項目は存在しない」も誤り＝ページネーションではnextが尽きるまで取得して初めて全件です。
2.3.3この節のまとめ
- Webhookは稀な変化・即時通知向けの逆呼び出し（サーバ→クライアントのPOST）。高頻度ポーリングの空振りとレート制限を同時に解消する
- レート制限の
429はRetry-Afterに従い指数バックオフで頻度を下げる。間隔を詰めるのは逆効果 - ページネーションでは
next（またはlimit未満の返件）まで繰り返し取得して全件化する。1ページ目＝全件ではない
進捗の記録にはログインが必要です。
理解度チェック
（軽い確認用）Q1. ネットワーク機器のアラートを「発生した瞬間に」担当者へ通知したい。現状は5秒ごとにアラートAPIをポーリングしているが、アラートは1日数回しか発生せず、大半の呼び出しが空振りで `429 Too Many Requests` も頻発する。最も適切な設計変更はどれか。
Q2. `GET /v1/clients?limit=100` を1回呼び、返ってきた100件を「全クライアント」として集計したところ、実際の接続数と合わない。応答ボディには `"next": "/v1/clients?limit=100&offset=100"` が含まれていた。原因と正しい対応として最も適切なものはどれか。
Q3. あるAPIクライアントが `429 Too Many Requests`（`Retry-After: 30` 付き）を受け取った後、待機せずに即座に同じリクエストを連打し続けている。この挙動の問題点と正しい対処として最も適切なものはどれか。