概要

コンシューマーファーストの原則でWeb APIを設計・進化させる

想定読者

APIを設計・公開する立場のバックエンドエンジニアや、チームのAPI仕様策定を主導するテックリード

こんな人には向いていない

• GraphQL・gRPC・WebSocketなど非REST系インターフェイスの実装方法を求めている場合は対象外
• Spring Boot・Djangoなど特定フレームワークの具体的なコーディング手順を求めているエンジニアには実装例が薄い（本書は実装ありきではない設計原則を扱う）
• APIを『消費する』だけのフロントエンドエンジニアで設計責任を負わないポジションには不要な章が多い

この本で身につくこと

• コンシューマー(利用者)視点でエンドポイント・レスポンス構造を設計できる
• ビジネス目標と技術目標のバランスを取るAPI要件収集の進め方を理解できる
• 可用性・拡張性・堅牢性を備えたAPIを段階的に進化させる設計方針を習得できる
• メンテナンス性と利用者獲得を意識したAPIドキュメントの記述・整備方法を実践できる
• コマース系システムを一貫した題材として、実世界のユーザー指向API設計の勘所を体得できる

ハイライト(外部からの言及)

要件を収集する方法、ビジネス目標と技術目標のバランスを取る方法、および消費者第一の考え方を採用する方法について、仔細に検討し、より使いやすく可用性に富み、拡張性と堅牢性をもつAPI構築への道を詳解してくれます。 — 出典

本書が『消費者第一』という設計軸をどのような問いの立て方で実践するかを最も端的に示している箇所

実装ありきではないスタイルで、APIのすべてを語り尽くしています。また、メンテナンス性や、より多くのユーザーを獲得するためのドキュメントの記述・完備方法なども詳解します。 — 出典

設計思想とドキュメント戦略の両方を扱う本書のスコープを明確に示している

「Web API の設計」という本を読んでみて、APIのドキュメント作成に OSA（OpenAPI Specification）が取り上げられていたので触ってみた — 出典

読者が本書のドキュメント章を読んでOpenAPI Specificationを実際に試した体験談。設計原則の学習が具体的なツール実践へとつながるという本書の実用性を示している

読了後にできること

Before(読む前): 突貫でAPIを作り始め、使い勝手や拡張性の問題は実装後に顕在化するまで意識できていない

After(読み終えた後): コンシューマー視点で要件を整理し、可用性・拡張性・堅牢性を設計段階から作り込む視点と判断軸を持てる

章立て

第1章 APIデザインとは何か

第1部 APIデザインの基礎。本書の問題設定とゴール

第2章 ユーザーを意識したAPIを設計する

本書独自の視点。API のユーザー(消費者)視点で設計を組み立てる

第3章 プログラミングインターフェイスを設計する

リソース・アクション・データ表現の三軸で API 構造を定義する章。第 2 章の消費者視点を、具体的なインターフェイス設計の手順に落とし込む橋渡し役。

第4章 API記述フォーマットを使ってAPIを記述する

OpenAPI 仕様の具体的な使い方。スキーマ駆動開発の起点

第5章 単純明快なAPIを設計する

第2部 ユーザブルなAPIの設計

第6章 予測可能なAPIを設計する

命名規則・ステータスコード・エラー形式の一貫性。読みやすい API の核心

第7章 うまく整理された簡潔なAPIを設計する

エンドポイントの粒度・グルーピング・不要パラメータの削除など API の冗長さを排除する章。第 5・6 章の原則を踏まえた上で、実務で起きがちなエンドポイント増殖の抑制策を学べる。

第8章 セキュアなAPIを設計する

第3部 コンテキストに応じたAPIデザイン。認証認可・OAuth 2.0 の前提

第9章 APIの設計を進化させる

API バージョニング戦略。後方互換性の保ち方

第10章 ネットワーク効率のよいAPIを設計する

ページネーション・キャッシュ・一括更新など、ネットワーク転送量とラウンドトリップを削減する手法を扱う。パフォーマンス最適化の前に基本設計を固めてから読む章。

第11章 コンテキストに基づいてAPIを設計する

モバイル・パートナー・公開 API など利用コンテキストの違いが設計判断に及ぼす影響を扱う。第 8 章（セキュリティ）と合わせて読むと、コンテキスト別のアクセス制御の判断軸が整理される。

第12章 APIを文書化する

API ドキュメントの読み手別構成。実装と乖離させない方法論

第13章 APIを成長させる

本書の総括。API ライフサイクル管理

関連記事 / 参考情報

• 1年半のソフトウェアエンジニア長期インターンで出会ったオススメ本をたくさん紹介します — インターン経験者がAPI設計入門書として本書を推薦。実務参入前の必読書として位置づけている
• HTTPとRESTの基本 『網羅版：HTTPメソッドとレスポンスコード』 — REST APIのHTTPメソッドとステータスコードを網羅的に解説。本書と対にして読むと設計原則の理解が深まる
• SpringBootとスキーマ駆動開発で始めるWeb API 設計開発入門：前編 — SpringBootでのスキーマ駆動開発の実装手順を解説。本書の設計思想をJava/Springで実践する文脈で参照
• OpenAPI Specification を利用してAPI仕様書を作成する — OpenAPI仕様書の作成方法を実例付きで解説。本書が説くドキュメント整備の実装的な補足として参照できる
• Django REST frameworkでAPIドキュメントを自動生成 & ドキュメント画面からPOSTする方法 — Djangoを使ったAPIドキュメント自動生成の実装例。本書のドキュメント整備の重要性をPythonで具体化している

学習のヒント

• 本書は実装言語に依存しない設計原則を扱うため、読みながら自分が関わるAPI仕様書を手元に置き、各章の判断軸を実際の設計に当てはめる読み方が効果的
• コマース系サイトという一貫した題材で全章が構成されているため、最初から順番に読むことで設計判断の積み重なりが追いやすい
• ドキュメント章は「後で書く」と先送りしがちだが、設計とドキュメントの連動を早期に理解するために前半の章と並行して読むことを推奨
• OpenAPI/Swagger などの具体的なツール活用は本書のスコープ外のため、実装フェーズではスキーマ駆動開発の別資料を別途参照するとよい

前提知識

• HTTPのメソッド(GET/POST/PUT/DELETE)とステータスコード(2xx/4xx/5xx)の概念的な理解
• REST APIを利用する側としての経験（curlやSDKで外部APIを呼び出したことがある程度）
• Webアプリケーションにおけるフロントエンド・バックエンド分離の基本概念

次に読む本

RESTful Web Services Cookbook

本書がコンシューマー視点の原則論を扱うのに対し、同書は REST API の具体的なユースケース別レシピ（URI 設計・HTTP 動詞の使い分け・HATEOAS 等）を網羅する。本書で原則を把握した後、実際の設計決定の拠り所として参照すると判断の解像度が上がる。

Webを支える技術 —— HTTP，URI，HTML，そしてREST

本書が『なぜそう設計するか』の原則を示すのに対し、同書は HTTP・URI・REST の原理を歴史的経緯と仕様レベルから解説する。本書を読む前後どちらでも参照でき、設計判断の根拠をプロトコル仕様まで遡って確認したいときに有効。

OpenAPI / Swagger を用いたスキーマ駆動開発関連資料

本書は API 設計の原則とドキュメント整備の重要性を扱うが、OpenAPI Generator によるコード自動生成やバリデーションなどの具体的なツール活用は対象外。本書で設計方針を固めた後、スキーマ駆動開発の実装フローに移行する段階で参照すると、原則と実装の橋渡しができる。