Web APIを作ろうとしたとき、こんな疑問にぶつかったことはありませんか？
- POSTとPUTって、どう違うの？
- ユーザーを削除するURLって /deleteUser でいいの？
- ステータスコードって、200以外に何使えばいいの？
APIを設計していると、こうした“地味だけど重要”なポイントで迷うことがよくあります。
実はこういった迷いの多くは、「どんなルールでAPIを設計するのか？」 がはっきりしていないことが原因だったりします。
そこで登場するのが、REST（レスト） という設計思想です。
あまり聞き慣れない言葉かもしれませんが、実は私たちが普段使っている多くのWebサービスは、RESTの考え方をベースに作られています。
Laravel、Spring、Railsなど、使っているフレームワークに関係なく、RESTの基礎を知っておくと「API設計で迷わない軸」ができます。
本記事では、これからAPIを設計・実装しようとしている人向けに、
- RESTってそもそも何？
- URLやHTTPメソッド、どう使い分ければいい？
- ステータスコードの選び方ってあるの？
といったポイントを、わかりやすく＆実例を交えて 解説していきます。
RESTとは？Webの設計を支える“考え方”
REST（レスト）は、2000年にロイ・フィールドイング（Roy Fielding）が博士論文 『Architectural Styles and the Design of Network-based Software Architectures』 の中で提唱した、Webアーキテクチャに関する設計思想です。
論文全文はこちら（英語）： https://ics.uci.edu/~fielding/pubs/dissertation/top.htm
RESTはいわゆる「APIの仕様」や「技術」ではなく、“どう設計すればWebサービスは拡張性が高く、わかりやすくなるか？”というアーキテクチャスタイルのひとつです。
RESTの6つの設計原則（ざっくり要点）
- 統一インターフェース：APIの使い方が一貫していて学習コストが低い
- クライアント・サーバ：役割分離で柔軟な開発が可能に
- ステートレス：リクエストは毎回独立して完結
- キャッシュ可能：応答にキャッシュ可否を明示できる
- 階層構造：中間サーバやゲートウェイを意識した構成が可能
- コードオンデマンド（任意）：必要に応じてコードを送る仕組み（JSなど）
リソースとHTTPメソッド：正しいURL設計とは？
RESTの考え方では、URLは“リソース（＝データ）を表す名詞”として設計するのが基本。
そして、そのリソースに対して何をするのかは、HTTPメソッド（GET、POST、PUTなど）で表現します。
典型的なREST設計の例：
| メソッド | エンドポイント | 意味 |
|---|---|---|
| GET | /users | ユーザー一覧の取得 |
| GET | /users/123 | 特定ユーザーの取得 |
| POST | /users | 新しいユーザーの作成 |
| PUT | /users/123 | ユーザー情報の全体更新 |
| PATCH | /users/123 | ユーザー情報の一部更新 |
| DELETE | /users/123 | ユーザーの削除 |
RESTではURLは「操作の対象（＝リソース）」を示し、 「どんな操作をするのか」はHTTPメソッドで表現します。 URLが“名詞”、HTTPメソッドが“動詞”の役割を担う、という考え方です。
このルールを守ることで、エンドポイントが直感的で読みやすくなり、他の開発者とのコミュニケーションもスムーズになります。
現実世界のAPI設計：カスタムメソッドという選択肢
REST原則に従って設計していても、標準的なCRUD操作では表現しにくい処理もあります。
たとえば：
- ユーザーのアクティベーション
- アカウントの一時停止
Googleのカスタムメソッド
POST /users/{id}:activate
POST /users/{id}:suspendこれはRESTの”名詞＋HTTPメソッド”という原則からは外れますが、 **「わかりやすく、意図が明確に伝わる」**という点で非常に実用的です。
📚 Google Cloud API Design Guide
他にも同様の例は多数
- GitHub API：
POST /repos/:owner/:repo/merges - Microsoft Graph API：
POST /me/sendMail - Stripe API：全てPOSTで処理（例：
/subscriptions/{id}/cancel）
大事なのは、REST原則を理解したうえで「意図的に」例外を作ることです。
HTTPステータスコードの意味、ちゃんと使えてる？
ステータスコードは、APIが「何を返すか」だけでなく「どう返すか」を示す大事なパーツです。
| コード | 意味 | 使用例 |
| 200 | OK（成功） | 通常の成功レスポンス（GETなど） |
| 201 | Created（作成成功） | リソースが新しく作成された（POST） |
| 204 | No Content（内容なし） | 成功だが返すデータがない（DELETEなど） |
| 400 | Bad Request（リクエスト不正） | パラメータ不足、形式不正など |
| 401 | Unauthorized（認証エラー） | トークン未付与、期限切れなど |
| 403 | Forbidden（アクセス拒否） | 権限不足、アクセス不可 |
| 404 | Not Found（見つからない） | 指定したリソースが存在しない |
| 409 | Conflict（リソース競合） | すでに存在する、重複チェックなど |
| 422 | Unprocessable Entity（処理不能） | バリデーションエラーなど入力エラー |
| 500 | Internal Server Error | サーバー内部のエラー（バグなど） |
| 503 | Service Unavailable | サーバーメンテ中や過負荷など |
RESTでは、ステータスコードも「リソースの状態変化を表現する手段」として使われます。
REST設計は“原則”と“現実”のバランスが大事
RESTの原則を学ぶことは、API設計において大きな武器になります。
ただし、原則に固執しすぎて設計が複雑になってしまっては本末転倒です。
- 基本は「リソース×HTTPメソッド」の組み合わせ
- でも、伝わりやすさや業務要件を重視するなら、柔軟に“逸脱”することもアリ
- ステータスコードや冪等性など、HTTPの基礎もRESTの一部として理解する
RESTは“設計の指針”であり、“チェックリスト”ではありません。 あなたのAPIが、「使いやすく、意図が伝わる」ものになっていれば、それはきっとREST的です。
コメントを残す