「なんとなく設計」の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 プロトコルに用意されているためだ。

ただし /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 を数時間遮断することで、対応が遅れている開発者に移行を促す手法だ。廃止を知らせる告知から段階的な遮断まで、利用者への影響を最小化しながら進める手順が示されている。

DevBookPath のマップで確認する

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

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

---

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