APIは「利用者のためのUI」だ：Arnaud Lauret『Web APIの設計』

Web APIは一度公開すると後から壊しにくく、設計の良し悪しがそのまま開発者体験を左右する。Arnaud Lauret（「API Handyman」として知られる）の『Web APIの設計』は、APIを「サーバーとクライアントの間でデータを運ぶ仕組み」ではなく「利用する開発者が触れるプロダクト」として捉え直し、使いやすさを設計する原則をまとめた一冊だ。

1. APIは利用者のためのUIである

本書の出発点は、APIの目的を「それを使うアプリ開発者ができるだけ成功すること」に置く点だ。

著者は、洗濯機やキーボードといった日常品の使いやすさを引き合いに出す。マニュアルなしで操作できる道具のように、APIも利用者が直感的に理解し、迷わず使えるべきだという。これは、認知心理学に基づくデザインの考え方（ドン・ノーマンの議論に近い視点）をAPI設計に持ち込んだものだ。

「とりあえずデータを全部返すエンドポイントを作ればよい」という実装中心の発想を、利用者中心へと転換させるのが本書の核にある。

2. 内部実装と外部インターフェースを分ける

本書が繰り返し戒めるのが、データベースのテーブル構造をそのままAPIとして公開することだ。

内部構造を露出させると、将来テーブルを変更したときにAPIの変更へ直結し、利用者を巻き込む強い結合が生まれる。代わりに、クライアントが必要とする操作に基づいて論理的なリソースを設計する。たとえば内部的に複数テーブルへまたがる「注文」も、利用者には一つのまとまったリソースとして見せる。

この分離があることで、内部実装を独立して進化させられるようになる。

3. バージョニングは「変更容易性とのトレードオフ」で考える

ビジネスの成長に伴ってAPIは変化する。問題は、既存の利用者を壊す破壊的変更をどう扱うかだ。

本書はパスにバージョンを埋め込む方法（/v1/... のような形）などを示しつつ、新旧バージョンを並行稼働させるインフラ・運用コストと、利用者への影響範囲を天秤にかける判断を求める。バージョニングは技術的な作法であると同時に、誰がいつ移行できるかという運用の問題でもある。

4. 予測可能であること

利用者を混乱させる最大の要因は、一貫性のなさだ。

あるエンドポイントでは数値、別のエンドポイントでは文字列、というように同じ概念の表現がぶれると、利用者は毎回確認を強いられる。データフォーマット、命名規則、エラー時のステータスコードをシステム全体で統一し、利用者が次の挙動を予測できる状態を保つ。

一方で本書には注意点もある。読者レビューでは、API設計を実際に行わない人や初学者にとっては内容が重く、セキュリティ（OAuth 2.0 の認可フロー）など抽象度の高い章は別途学習が必要だ、という声もある。実装に踏み込む立場の中級者が最も価値を得やすい一冊と言える。

DevBookPath のマップで確認する

この本の前後の読書順は、DevBookPath のグラフで確認できます。

👉 バックエンド開発の地図を見る

---

本記事のリンクには Amazon アソシエイト等の広告が含まれる場合があります。リンク経由の購入で運営者に紹介料が支払われることがあります。