API と外部連携

API は、サービス同士が決まった形でデータをやりとりする窓口です。自社の画面とサーバーの間にも、自社と外部サービス（決済・地図・メールなど）の間にもあります。窓口の形を変えると、それを使っている側が壊れることがあります。

後方互換とは、古い使い方のままでも動き続けることです。項目を足すのはたいてい安全ですが、項目の削除・名前の変更・意味の変更・必須にするは使う側を壊します。特にスマホアプリは古い版を使い続ける人がいるので、サーバーは何か月も古い形に対応し続ける必要があります。「この変更は互換を壊しますか？古い版はいつまで残りますか？」は仕様の段階で確認します。

Web の「バージョニングと後方互換」

SRE の「タイムアウトの種類と設定の考え方」

API の仕様書には、どの URL に・何を送ると・何が返るかが書かれています。OpenAPI という形式で書かれていることが多く、画面で一覧を見られるようにしているチームもあります。

GET /orders?status=shipped&limit=20
→ 200 OK
{ "orders": [ { "id": 101, "total": 3000, "status": "shipped" } ],
  "next_cursor": "abc" }

仕様書が読めると、「この画面を作るのに API の変更は要る？」を自分で見当をつけてから聞けるので、見積もりの会話が速くなります。

決済・地図・メール・AI など、外部のサービスを使うと早く作れますが、相手が止まる・遅くなる・値上げする・終わることの影響も受けます。企画の段階で、そのときの体験を決めておきます。

画面を出すために、サーバーは決済・地図・おすすめ・社内の別システムなど、ほかのサービスを呼んでいます。呼んだ先が遅い・止まっているときにどうするかは、エンジニアの設定であると同時に、そのとき利用者に何を見せるかという仕様の問題でもあります。ここは PdM が決めに加わる場面です。

タイムアウトは「何秒待って返事がなければあきらめるか」の上限、リトライは失敗したときに自動でやり直すことです。上限がないと、相手の遅れで自社のサーバーまで詰まり、関係のない画面も遅くなります。

「なくても困らない部分」（おすすめ・レビュー件数など）は、取れなければ省いて画面を出す、と決めておくと、外部の障害でもサービス全体は使えます。

下の「ブラウザで試す」の図は、スマホのアプリが注文を送る例です。返事が届かないままタイムアウトしたあと、1秒・2秒・4秒と間をあけてやり直し、同じ「冪等キー」（この操作を見分ける番号）を付けて送り直すので、注文が2つできずに前回の結果が返るところまでを追えます。上の表の「やり直してよい処理か」で、決済を「二重請求にならない作りが先」としているのは、この仕組みがあって初めて安全にやり直せるからです。

Webhook は、外部サービスで何かが起きたとき（支払いが完了した、など）に、相手から自社へ知らせてもらう仕組みです。自分から定期的に聞きに行くポーリングより反映が速く、無駄な問い合わせも減ります。

「支払い完了の知らせが届かなかったら注文はどうなるか」は、仕様で決めておくべき大事なエッジケースです。

外部 API の多くには、回数制限（一定時間に呼べる上限。超えると 429 が返る）と、従量課金（呼んだ回数や量に応じた料金）があります。利用者が増えたり、画面を開くたびに呼ぶ作りにしていたりすると、ある日急に止まる・請求が跳ねる、ということが起きます。

結果をキャッシュして呼ぶ回数を減らす、まとめて呼ぶ、上位のプランに変える、などの対策は、試算の数字があればエンジニアと選べます。