API 設計で迷わないために──『Webを支える技術』が示す URI・HTTP・REST の設計根拠

API のエンドポイントを設計するとき、/getUser と /users/1 のどちらが正しいか、POST と PUT をどう使い分けるかで手が止まる——その詰まり方は、HTTP や REST の設計思想を学ぶ機会がなかったことに起因することが多い。

山本陽平著『Webを支える技術 HTTP、URI、HTML、そしてREST』（技術評論社、2010年）は、Web の基盤となる 3 つの技術（URI・HTTP・HTML）と REST アーキテクチャスタイルを、設計判断の文脈ごと解説する。2010 年刊行だが、URI 設計と HTTP の基本原則を扱う部分は現在も参照できる内容だ。

1. リソースを「名詞」、メソッドを「動詞」として分離する

REST の根幹にある考え方は、操作対象となる概念をリソース（名詞）として URI で表現し、そのリソースに対する操作を HTTP メソッド（GET・POST・PUT・DELETE という動詞）に委ねることだ。

この分離を徹底すると、/deleteUser や /updateOrder のようなエンドポイントが不要になる。DELETE /users/1 や PUT /orders/5 で同じ意味が表現できるからだ。エンドポイントの増殖が防がれ、初めて API を使う開発者が動作を予測しやすくなる。

本書は GET・POST・PUT・DELETE それぞれのメソッドが持つ「べき等性」と「安全性」も整理する。GET は何度呼んでも状態が変わらない（べき等かつ安全）、PUT は複数回実行しても同じ結果になる（べき等だが安全ではない）という性質の違いが、どのメソッドをどの操作に使うべきかの判断基準になる。

2. 「なぜこの形式なのか」を歴史的経緯から理解する

HTTP のヘッダ仕様を見ると、見慣れない形式が多い。本書はそれらが誕生した経緯を丁寧に解説する。たとえば HTTP ヘッダの形式は電子メールのメッセージ仕様（RFC822）を継承したものだ、という事実は、仕様を暗記する代わりに「なぜこうなっているのか」を理解する手がかりになる。

ステータスコードの体系も同様で、3xx がリダイレクト、4xx がクライアントエラー、5xx がサーバーエラーを表すという構造が、どのような設計判断から生まれたかを追えると、適切なコードを選ぶ判断が根拠を持てるようになる。

3. ステートレスという原則と、Cookie セッションという妥協

REST の重要な制約のひとつが「ステートレス性」だ。サーバー側でクライアントの状態を持たない設計は、負荷分散やスケールアウトを容易にする。しかし現実のウェブアプリケーションでは、ログイン状態の維持のために Cookie を使ったセッション管理が必要になる。

本書はこの Cookie によるセッション管理を「理想の REST から外れた妥協」として位置づけ、理論と現実のトレードオフを正直に論じる。理想論だけでなく、どこで原則を曲げているかを自覚した上で設計することを求める姿勢——これが実務での設計判断に根拠を与える。

---

2010 年刊行書の読み方について: HTML5 が策定中として扱われるなど、内容の一部は現代と乖離している。Atom や microformats の章は現在の開発では参照頻度が低い。URI 設計・HTTP メソッド・ステータスコード・REST アーキテクチャの章に集中して読むことで、現在の開発に直結する知識を効率よく吸収できる。

DevBookPath のマップで確認する

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

バックエンドの地図を見る ／ フロントエンドの地図を見る

---

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