API

API とは

API (Application Programming Interface) は、ソフトウェア同士が機能やデータをやり取りするための接続規約だ。あるプログラムが持つ機能を、外部から決められた手順で呼び出せるようにする「窓口」と考えると分かりやすい。内部の作りを知らなくても、決められた形式でリクエストを送れば結果が返ってくる。

レストランの注文に例える

API はよくレストランに例えられる。客 (利用側プログラム) はメニュー (API の仕様) を見て注文し、ウェイター (API) が厨房 (提供側システム) に伝え、料理 (データ) を運んでくる。客は厨房の調理方法を知る必要がない。この「内部を隠して窓口だけ公開する」考え方が API の本質だ。

Web API の仕組み

外部に公開される API の多くは、HTTP を使ってやり取りする Web API である。

要素	役割
エンドポイント	機能ごとのアクセス先 URL
リクエスト	何をしてほしいかの要求
レスポンス	結果のデータ (多くは JSON 形式)

天気情報・地図・決済・AI など、外部サービスの機能を自分のアプリに組み込めるのは API のおかげだ。

Web API の設計様式として広く使われる REST (Representational State Transfer) は、Roy Fielding が 2000 年の博士論文 (カリフォルニア大学アーバイン校) で提示したアーキテクチャスタイルに由来する。資源を URL で表し、それに対する操作は HTTP メソッドで表す、という役割分担はここから来ている。

メソッドの意味を守る理由

HTTP メソッドには仕様上の性質が定められており、これを外れた API は利用側の再送処理を壊す。RFC 9110 では GET・HEAD・OPTIONS・TRACE が「安全」(サーバーの状態を変えない要求) とされ、PUT・DELETE と安全なメソッドが「冪等」(同じ要求を何度送っても、1 回送ったときと結果が同じ) とされている。

冪等な要求は、レスポンスを受け取る前に通信が切れた場合に送り直しても副作用が増えない。一方 POST は冪等でないため、同じ仕様は冪等と分かる根拠がない限り自動再送しないことを求めている。決済処理を POST で受けている API に、利用側が素朴なリトライを入れて二重課金が起きるのはこの性質を無視した結果だ。逆に、状態を変える操作を GET に載せるのも危険で、中継の再取得や利用側の再読み込みが更新を引き起こす。

設計・利用上の注意点

API は一度公開すると、利用者がそれに依存するため、後からの変更が難しくなる。仕様を安易に壊すと、つながっている全システムに影響する。壊れるのは利用側が前提にしていたものを取り上げたときで、フィールドの削除・改名、必須パラメータの追加、既存のエラーコードの意味の変更が典型だ。逆に、レスポンスへの項目追加や任意パラメータの追加は、未知の項目を無視する利用側であれば壊さない。

この区別がつくと、版を分ける必要があるのは前者だけだと分かる。分け方には URL パスに版を含める方式 (/v1/users) と、リクエストヘッダーで版を指定する方式がある。前者は使う版が URL から見えて切り替えやすく、後者は URL を資源の識別子として保てる。どちらを選んでも、旧版をいつまで動かすか (並行運用の期間と廃止の予告) を決めていなければ、版を分けた意味は薄い。利用側では、認証情報 (API キー) の漏洩防止、レート制限への配慮、エラー時の処理を設計に織り込む必要がある。「つなぐのは簡単だが、壊さず保つのは難しい」のが API の勘所だ。

理解を深めるには関連書籍が役立つ。