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

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

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

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

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

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

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

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

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

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

flowchart LR
    subgraph NG["❌ DB構造をそのまま公開"]
        N1["GET /order_items\nGET /order_details\nGET /user_billing\n（内部テーブルが透けている）"]
    end
    subgraph OK["✅ 利用者視点のリソース"]
        O1["GET /orders/:id\n（内部は3テーブル結合でも\n論理的に一つのリソース）"]
    end
    style NG fill:#fce8e8,stroke:#e53935
    style OK fill:#e8f8e8,stroke:#4caf50

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

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

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

4. 予測可能であること

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

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

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

5. どんな設計の詰まりに効くか

「公開したAPIが使いにくいとフロントエンド担当から指摘が続くが、何をどう直せば良くなるのか判断できない」——この詰まりは、APIを利用者が触れるプロダクトとして評価する視点を持たないまま、内部の都合で設計していることに原因があることが多い。本書のコンシューマーファーストの原則は、その評価軸を与える。

もう一つは、DBのテーブル構造をほぼそのままAPIにしてしまい、内部を変更するたびに利用者への影響調整に追われる状況だ。内部実装と外部インターフェースを分ける考え方と、バージョニングを運用コストとのトレードオフで捉える視点が、この結合をほどく手がかりになる。

6. 読むべき人と、まだ早い人

向いている人：

• REST/HTTP でWeb APIを設計・実装する立場で、使いやすさの判断基準を明文化したい中級バックエンドエンジニア
• OpenAPI などの記述フォーマットを使って設計を進めたい開発チーム
• 既存APIの使いにくさを指摘されているが、直す方針を言葉にできていない人

向いていない人：

• API設計に直接関わらない、またはプログラミングをこれから学ぶ人（本書は実装に踏み込む中級者向けで、初学者には内容が重い）
• OAuth 2.0 など認可・セキュリティ設計を本格的に学びたい人（本書でも触れるが抽象度が高く、その領域は別の専門書で補う必要がある）

7. 次に開く本と、最初の一歩

本書で「使いやすいAPIをどう設計するか」を押さえたら、次は設計したAPIの品質をどう守るかへ関心が向く。『Web APIテスト技法』は、設計した仕様が実際に期待通り動き続けるかを検証する観点を与え、設計と検証を往復できるようにする。REST 以外の選択肢に視野を広げたいなら、クエリ言語として設計思想の異なる『初めてのGraphQL』や、スキーマ駆動でサービス間通信を組む『gRPCアップアンドランニング』へ進むと、本書で得た「利用者を意識した設計」を別のプロトコルでも活かせる。より短く実践寄りに REST/HTTP の作法を確認したい場合は、前提として挙げられる『Web API: The Good Parts』が軽い併読先になる。

最初の一歩としては、自分たちのAPIのエンドポイントを1つ選び、それがDBのテーブル構造をそのまま映していないか——内部実装が外部インターフェースに透けていないかを点検してみるのがよい。透けている箇所こそ、本書の分離の原則が最初に効く場所だ。

筆者の体験から

『Web API: The Good Parts』で作法は一通り押さえたつもりだったが、APIレビューで指摘を出すたびに「なぜダメか」を原則として説明できず、単なる好みの押し付けに見えてしまうことが続いていた。担当者ごとに設計基準がばらばらな状態をどうにかしたくて本書を読み始めた。

読んだ後、レビューの指摘の仕方が変わった。「このAPIはダメ」ではなく「内部のDB構造が利用者に透けている」と原則を根拠に言えるようになった。ある業務システムで、急いで足したエンドポイントが注文明細テーブルの列名をほぼそのままJSONのキーで返していたことがある。指摘してもピンと来ていなかった担当者に、「洗濯機の配線を見せられても困る、外から見えるボタンだけでいい」という例えを出したところ合点がいった顔をしていた。そのエンドポイントは後日、一つの「注文」リソースとして作り直した。

正直、セキュリティ（OAuth 2.0の認可周り）の章は抽象度が高く、読んだだけでは実装のイメージが湧かなかった。

DevBookPath のマップで確認する

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

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

📖 Amazon で購入する

---

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