REST API の設計原則

REST API の設計原則

解説

このレッスンで分かること

• REST は HTTP のメソッド・URL・ステータスコードを「リソース指向」で組み合わせた API 設計の指針です
• 安全性 (GET/HEAD)、冪等性 (GET/PUT/DELETE)、ステートレス、統一インターフェースが核となる制約
• 完全な「教科書 REST」より、原則を理解した上で実用的に崩す判断が長期メンテに効きます

解説

REST API の設計原則 とは

リソース指向、ステートレス、URL 設計など REST の基本を理解します。本レッスンでは、REST API の設計原則 の基本から実際の使いどころまでを整理し、現場で迷わず使える形に落とし込みます。

HTTP メソッドの安全性・冪等性・用途まとめ

• 安全でないメソッド (POST 等) はブラウザの prefetch 対象から外れる
• 冪等性が保証されていれば、ネットワーク再送で同じ操作が二重発火しても破壊的にならない
• DELETE /users/1 を 3 回呼んでも結果は「ユーザー 1 が存在しない」で同じ ⇒ 冪等

このレッスンで学ぶこと

Web API の代表的な設計スタイルである REST の原則を学びます。Roy Fielding が定義した 6 つの制約を踏まえ、現実的な REST API 設計のコツを掴みましょう。

REST とは

REST (REpresentational State Transfer) は、2000 年に Roy Fielding が博士論文で提唱した Web アーキテクチャの設計原則です。HTTP の特性を活かして、リソース指向で API を設計するスタイルです。

「REST API = HTTP で叩く JSON API」と理解されがちですが、本来は単なる JSON API ではなく、いくつかの制約を満たす設計思想を指します。

6 つの制約

REST の制約は次のとおりです。

1. クライアント・サーバー型 — UI とデータを分離。それぞれが独立に進化できる。
2. ステートレス — 各リクエストに必要な情報を全部入れる。サーバーはセッションを覚えない。
3. キャッシュ可能 — レスポンスがキャッシュ可能か明示し、Web 全体のスケーラビリティを上げる。
4. 統一インターフェース — URL は名詞、メソッドは動詞という統一規則。
5. 階層化システム — クライアントから見て、直接サーバーと話しているか CDN/プロキシ越しか区別する必要がない。
6. コードオンデマンド (任意) — サーバーが JS など実行可能コードをクライアントに送ることがある。

実務で特に重視されるのは 2, 3, 4 です。

リソース指向の URL 設計

REST では URL を「リソースの住所」として設計します。

• GET /users — ユーザー一覧
• GET /users/123 — ID 123 のユーザー詳細
• POST /users — 新規ユーザー作成
• PUT /users/123 — ユーザー 123 を完全更新
• PATCH /users/123 — ユーザー 123 を部分更新
• DELETE /users/123 — ユーザー 123 を削除

動詞は HTTP メソッドが担うので、URL は名詞 (リソース) だけで構成します。POST /createUser や POST /deleteUser は REST 的にはアンチパターンです。

ステータスコードの活用

REST API ではステータスコードを正しく使い分けます。

• 200 OK — 通常成功
• 201 Created — リソース作成成功 (POST)
• 204 No Content — 成功したがボディなし (DELETE で多用)
• 400 Bad Request — リクエスト不正
• 401 Unauthorized — 認証されていない
• 403 Forbidden — 認証はされているが権限なし
• 404 Not Found — リソースなし
• 409 Conflict — 競合 (重複登録など)
• 422 Unprocessable Entity — バリデーションエラー
• 429 Too Many Requests — レート制限

500 番台 (サーバーエラー) を 200 で包んで「成功っぽく見せる」のは絶対にやめましょう。クライアント側の汎用エラーハンドリングが効かなくなります。

ページネーション

リスト系 API は必ずページネーションを設計します。代表的な 2 つのスタイルは下記です。

• オフセットベース — ?page=2&limit=20 のように開始位置を指定
• カーソルベース — ?cursor=abc123&limit=20 のように直前の最後の ID を渡す

データ量が大きい / リアルタイムで増減するときはカーソルベースが堅牢です。一方、UI に「ページ 1 2 3...」と表示したい場合はオフセットベースが直感的。

バージョニング

API は時間とともに変更が必要になります。代表的なバージョニング方法は下記です。

• URL パス — /v1/users, /v2/users
• ヘッダー — Accept: application/vnd.example.v2+json
• クエリ — ?version=2

URL パスが最もシンプルで実装しやすく、運用でも見通しが良いです。

まとめ

このレッスンの要点は、リソース指向の URL / メソッドの安全性・冪等性 / ステータスコードの正しい使い分け の 3 点です。実務でこれらを切り分けて説明できるようになると、設計レビューや障害対応の精度が一段上がります。

理解度チェック

Q. 次のうち、HTTP メソッドの「冪等」性を持たないものはどれ？

1. GET
2. PUT
3. POST
4. DELETE

答えを見る

正解は 3。POST は新規作成系で、同じリクエストを 2 回送ると 2 件作成される可能性があるため非冪等。GET/PUT/DELETE は何度実行しても結果が同じ (冪等) です。

出典 (References)

• Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures (2000)
• MDN — HTTP メソッド
• IETF RFC 9110 — HTTP Semantics

最終更新: 2026-05-28

関連レッスン

• HTTP の基本
• HTTP メソッド
• HTTPS と TLS ハンドシェイク
• HTTP/2 と HTTP/3 (QUIC)

よくある質問

Q. GET と POST はどう使い分けますか？

A. 「取得して副作用がない」なら GET、「作成・更新など状態を変える」なら POST が原則です。GET は URL にパラメータが入りキャッシュも効きますが、POST はボディに乗せられ大きなデータも送れます。冪等性も GET は持ち、POST は持たないという違いがあります。

Q. ステータスコードは何を返すべき？

A. 成功は 2xx、リダイレクトは 3xx、クライアントエラーは 4xx、サーバーエラーは 5xx が大原則です。新規作成は 201、認証失敗は 401、権限不足は 403 を返すと REST 慣習に沿った設計になります。200 で全部返すのは避けてください。

Q. REST と GraphQL の違いは？

A. REST はリソース単位のエンドポイント、GraphQL は単一エンドポイントでクエリ言語を使って欲しいデータを指定します。フロントの要件が頻繁に変わるなら GraphQL、シンプルな CRUD なら REST がメンテしやすいことが多いです。

次のレッスン

次は DNS とは で、リソース指向、ステートレス、URL 設計など REST の基本を理解します を学びます。

事前確認 — 進む前に次の 3 つができることを確認しましょう。

1. REST API の要点を自分の言葉で説明できる
2. このレッスンの最小コード (または操作手順) を見ずに書ける
3. 練習問題やクイズで間違えた箇所を読み直して理解した

理解度チェック (30 秒)

Q. REST API とは何か、1 文で説明してください。

関連レッスン

• HTTP/2 と HTTP/3 (QUIC)
• HTTPS と TLS ハンドシェイク
• HTTP メソッド