API 連携

かんたんに言うと

API（Application Programming Interface、アプリケーション・プログラミング・インターフェース） とは、二つのシステムのあいだで「取り決めた通信のしかた」のことです。データが欲しいフロントエンドは、バックエンドの厨房にいきなり押し入ることはできません。API というカウンターを通します。取り決めた形式でリクエストを出し、バックエンドが取り決めた形式で返事をするのです。

よい API には明確な契約があります。リクエストに何を載せるべきか、レスポンスはどんな形か、エラー時にはどんなコードを返すか。契約が明確なら、フロントエンドとバックエンドはそれぞれ独立して開発でき、AI に正しい連携コードを生成してもらうのも楽になります。

アーキテクチャ

動作の流れ

よい契約と悪い契約

API が連携しやすいか、それとも頭痛の種かの違いは、結局のところ契約に行き着きます。

• よい契約は、明確（リクエストとレスポンスの形がはっきり書かれている）で、安定している（あなたの知らぬ間に勝手に変わらない）。ドキュメントがあり（各項目の意味を調べられる）、バージョンがある（新版は /v2/ で出し、古い /v1/ はそのまま動く）。
• 悪い契約は、何の予告もなく変わり、それに依存するものをすべて壊す。生のデータベース列やスタックトレースのような内部の詳細まで漏らす。そしてドキュメントがなく、試行錯誤を重ねてふるまいを探るしかない。

まとめ

• API ＝ システム間で「取り決めた通信の窓口」。
• 肝心なのは契約：リクエスト形式、レスポンス形式、エラーコード。
• 契約の変更にはバージョンを付ける（例：/v1/、/v2/）。一つの変更ですべてが壊れるのを防ぐ。