「なんとなく設計」のAPIから脱却する──『Web API: The Good Parts』の URI・HTTP・バージョン管理

API の設計レビューで「なぜこのエンドポイント名にしたんですか？」と聞かれて答えに詰まる。HTTPステータスコードを 200 か 500 しか使っていない。バージョン管理の方針が決まっていない——こういう状況は、設計の基準が定まっていないことの表れだ。

水野貴明著『Web API: The Good Parts』（オライリー・ジャパン、2014年）は、RESTful な API 設計の判断基準を一冊に整理した。2014年刊行だが、URI 設計・HTTP 活用・バージョン管理という核心の部分は現在も参照できる。

1. 「読んで意図がわかる」URI 設計の原則

本書が示す URI 設計の出発点は、ドキュメントを読まなくても使い方が推測できる「Hackable」な構造だ。

具体的には、URI に .php などの実装技術を露出させない。操作対象は名詞の複数形で表現する（例：/users）。アクションは URI のパスではなく HTTP メソッドで表現する——GET・POST・PUT・DELETE という動詞が既に HTTP プロトコルに用意されているためだ。

flowchart LR
    subgraph NG["❌ 感覚的な設計"]
        N1["GET /getUserList"]
        N2["POST /createUser"]
        N3["GET /deleteUser?id=1"]
    end
    subgraph OK["✅ 予測可能な設計"]
        O1["GET /users（一覧取得）"]
        O2["POST /users（新規作成）"]
        O3["DELETE /users/1（削除）"]
    end
    style NG fill:#fce8e8,stroke:#e53935
    style OK fill:#e8f8e8,stroke:#4caf50

ただし /search のように機能を明示する動詞をあえて URI に含めることを認める例外も示す。理論の徹底よりも実用性を優先するという判断を、どの場合に適用するかも含めて解説されている。

2. キャッシュとステータスコードで HTTP を使い切る

HTTP プロトコルには、通信量を減らし応答速度を上げるためのキャッシュ機能が備わっている。本書はその 2 つのモデルを整理する。

Expiration モデル（Cache-Control）はデータの有効期限を指定する。Validation モデル（ETag・Last-Modified）はデータが変わっていなければ空のレスポンス（304 Not Modified）を返す。これらを適切に設定するだけで、サーバーへの不要なリクエストを大幅に削減できる。

エラーハンドリングでは、500 一択ではなくステータスコードを意図に沿って使い分けることを求める。クライアント側の問題は 400 系、サーバー側の問題は 500 系として、詳細な原因を JSON ボディに含めて返す設計だ。エラーの原因をコードから特定できるかどうかは、デバッグコストに直結する。

3. Twitter の事例から学ぶ段階的廃止の手順

API は公開した瞬間から改訂が必要になる。仕様変更のたびに古い API を即廃止すると、既存クライアントが動かなくなる。

本書はバージョンを URI に含める方法（例：/v1/）を示した上で、安全な移行のための段階的廃止（Deprecation）手順を解説する。Twitter が v1.0 から v1.1 への移行時に行った「ブラックアウトテスト」の事例が取り上げられている。移行期限の直前に旧 API を数時間遮断することで、対応が遅れている開発者に移行を促す手法だ。廃止を知らせる告知から段階的な遮断まで、利用者への影響を最小化しながら進める手順が示されている。

4. この本が解決できる具体的な状況

「エンドポイントの命名ルールをチームで揃えたいが、基準がない」「ステータスコードを何番にすればいいか毎回迷う」「フロントチームから API の使いにくさを指摘されるが、何から直せばいいかわからない」——これらは、API設計の基準を学ぶ機会がなかったことが原因であることが多い。

本書は「判断基準のない設計」に基準を与えるための一冊だ。2014年刊行だが、URI設計・HTTP活用・バージョン管理という核心は現在も有効で、実務での判断に直接使える。

5. 向いている人・向いていない人

向いている人：

• REST API を設計しているバックエンドエンジニアで、設計の判断基準を明文化したい
• API のエンドポイント設計にチームで迷いが生じており、共通の参照先が欲しい
• フロントエンドエンジニアで、自分が使う API の設計を評価する視点を持ちたい

向いていない人：

• GraphQL や gRPC など REST 以外のプロトコルを今すぐ実践したい（本書は REST/HTTP に焦点を絞っている）
• 大規模 API のセキュリティ設計（OAuth2・OpenID Connect 等）を本格的に学びたい人

6. 読み終えた後のステップ

API の設計基準が身についたら、次はその API を「誰がどの権限で叩けるか」を制御する認証・認可の層に進むと、公開 API としての完成度が高まる。OAuth 2.0 を土台にした『OpenID Connect入門』が、トークンベースのアクセス制御を組み込む定石を示してくれる。

また、REST の基本設計を押さえたら、API を「契約」として記述・共有する実践に進む道もある。『Web APIの設計』は OpenAPI による仕様駆動の設計プロセスを扱い、場当たりでない一貫した API を組織で作るための型を与える。

筆者の体験から

テックリードになりAPIレビューを任されるようになった頃、指摘の基準が自分の中になく、若手に「では何が正解なんですか」と聞かれて言葉に詰まったことが何度かある。本書を境に、感覚で指摘する代わりにチェックリストと照らして指摘するようになり、クライアント起因は400系、サーバー起因は500系という使い分けをテンプレート化した。フロントチームからの問い合わせも目に見えて減った。

とはいえ、本書はREST/HTTPに範囲を絞っているため、外部公開APIで必要になったアクセス制御の設計は結局別の本で補うことになった。

印象に残っているのは、一覧APIのページネーションで後半ページの応答が遅くなり、更新中に同じデータが二重に表示される不具合が出た時のことだ。本書の相対位置指定と絶対位置指定の比較を思い出し、オフセット方式の弱点がそのまま出ていると気づいて、IDベースのカーソル方式に置き換えた。ページ番号ジャンプはできなくなったが、その画面ではもともと使われていなかった。

DevBookPath のマップで確認する

この本の学習パス上の位置づけ・前後の読書順は、DevBookPath のグラフで辿れます。

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

📖 Amazon で購入する

---

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