
Web APIを作ろうとしたとき、こんな疑問にぶつかったことはありませんか?
- POSTとPUTって、どう違うの?
- ユーザーを削除するURLって /deleteUser でいいの?
- ステータスコードって、200以外に何使えばいいの?
APIを設計していると、こうした“地味だけど重要”なポイントで迷うことがよくあります。
実はこういった迷いの多くは、「どんなルールでAPIを設計するのか?」 がはっきりしていないことが原因だったりします。
そこで登場するのが、REST(レスト) という設計思想です。
あまり聞き慣れない言葉かもしれませんが、実は私たちが普段使っている多くのWebサービスは、RESTの考え方をベースに作られています。
Laravel、Spring、Railsなど、使っているフレームワークに関係なく、RESTの基礎を知っておくと「API設計で迷わない軸」ができます。
本記事では、これからAPIを設計・実装しようとしている人向けに、
- RESTってそもそも何?
- URLやHTTPメソッド、どう使い分ければいい?
- ステータスコードの選び方ってあるの?
といったポイントを、わかりやすく&実例を交えて 解説していきます。
INDEX
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的です。