ブログ記事

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

著者: DevBookPath 編集部公開日: 2026-06-25更新日: 2026-07-16

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 は複数回実行しても同じ結果になる（べき等だが安全ではない）という性質の違いが、どのメソッドをどの操作に使うべきかの判断基準になる。

flowchart LR
    subgraph R["リソース（名詞）\nURI で表現"]
        U["/users/1"]
    end
    subgraph M["メソッド（動詞）\nHTTP で表現"]
        G["GET — 取得\n（べき等・安全）"]
        P["PUT — 更新\n（べき等）"]
        D["DELETE — 削除\n（べき等）"]
        POST["POST — 作成\n（非べき等）"]
    end
    G & P & D & POST --> U
    style G fill:#e8f8e8,stroke:#4caf50
    style P fill:#e8f4fd,stroke:#4a9eda
    style D fill:#fce8e8,stroke:#e53935
    style POST fill:#fff8e1,stroke:#f5a623

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

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

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

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

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

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

4. 設計判断を「感覚」でしか説明できないとき

「動くから名前は何でもいい」で済ませてきたが、コードレビューで「なぜ POST なのか」「なぜ 200 を返すのか」と問われると、自分が書いた URI・メソッド・ステータスコードが Web の原則に照らして適切なのかを言葉にできない——この詰まりは、フレームワークが裏側を隠してくれるほど起きやすい。本書は URI・HTTP・REST の仕様がなぜその形になったのかを解説するため、読み終えると「この設計にした理由」を仕様の言葉で説明できるようになる。お作法として覚えていた選択が、根拠を持った判断に変わる。

5. 今読むと効く人、後回しでよい人

効く人

フレームワークのお作法で日常の開発はこなせるが、自分の URI・メソッド・ステータスコードの選び方を論理立てて説明したい実務 1〜3 年目のエンジニア
外部向け Web API や分散システムのインターフェース設計を、初めて主導する立場になった人
感覚で身につけた Web の知識を、若手に筋道立てて教えるための共通言語がほしいテックリード

後回しでよい人

Web アプリをまだ自分で作ったことがない段階の人。仕様の解説が中心で具体的なコードは少なく、抽象度が高く感じられる。先にフレームワークで手を動かしてから戻ると読みやすい
HTTP/2・HTTP/3 や TLS、OAuth など発展トピックの実務解をすぐ必要としている人。本書はそこを扱わない

6. この本が引き受けていない範囲

限界も正直に押さえておきたい。記述は仕様と概念の解説に重心があり、特定言語での実装コードは最小限のため、実務経験がまだ浅いうちは「ドキュメントを読んでいるようで咀嚼しづらい」と感じる場面がある。また、現在の Web 運用で欠かせない HTTP/2・HTTP/3、TLS/HTTPS、OAuth 2.0 による認証認可、CDN を前提としたキャッシュ運用は本書の範囲外だ。ここで扱うのは変わりにくい原理であって、最新プロトコルの最適化やセキュリティ実務までは踏み込まない。原理を本書で固め、運用寄りの知識は後発の専門書で補う——その役割分担を意識して読むと、この限界はむしろ本書の使いどころをはっきりさせる。

7. 原理を設計判断へ変える次の一冊

原理を押さえたら、それを実際の API 設計に落とす段階へ進む。バックエンドや API の設計基準を固めたいなら『Web API: The Good Parts』が、HTTP の意味論に忠実な URI 設計・エラー表現・バージョニングの定石を与え、本書の原理を具体的な設計判断へ変換してくれる。フロントエンド側で速度に効かせたいなら『Webフロントエンドハイパフォーマンスチューニング』へ。HTTP のキャッシュやリソース読み込みの仕組みを本書で理解しておくと、最適化が「なぜ効くのか」を根拠から追える。最初の一歩としては、次に設計するエンドポイントで URI を名詞・操作をメソッドに割り当て直し、選んだステータスコードの理由を一行メモしてみるとよい。

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

筆者の体験から

前職の受託開発からWeb系に軸足を移した頃、外部向けAPIの設計を自分で決める場面が増えたが、URIの切り方もメソッドの使い分けも前任者のコードを真似て済ませていた。あるレビューで「更新なのになぜPOSTなのか」と聞かれ、言葉に詰まったのが読むきっかけだった。本書でリソースを名詞、操作をメソッドに分けるという考え方を知ってから、動詞の入ったエンドポイントをやめ、対象をリソースとして名詞化してから設計するようになった。Cookieによるセッション管理を「理想からの妥協」と位置づける書きぶりには、当初やや引っかかりを覚えた。ステートレスが理想なのは分かるが、実務でログイン状態を保つ必要がなくなるわけではない。読んだ少し後、業務システムの更新APIでPATCH /orders/{id}を選び、隣のチームのリーダーに理由を聞かれた際、対象の一部だけを更新するのでPUTの全体置換の意味論とは合わない、と説明できた。以前なら感覚でしか答えられなかったはずだ。

DevBookPath のマップで確認する

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

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

📖 Amazon で購入する

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

この記事を共有

この地図を共有