REST APIって結局なに?
「それっぽいAPI」から卒業するための最低限まとめ
APIを作る仕事をしていると、
一度はこんな会話をしたことがあると思います。
先輩「これ、REST APIでお願いします」
自分「はい!(RESTって…なんだっけ…?)」
そして生まれるのが、こういうやつ。
GET /getUser?id=1
POST /createUser
POST /deleteUserById
動くし、便利。
でもレビューでこう言われる。
「これ、RESTっぽくないですね」
は?動いてるじゃん。
今回はそんな
"雰囲気でRESTやってた自分"を供養する記事です。
若手エンジニアの「REST分かったつもり」を
ちゃんと分かったに変えます。
まず結論:RESTは「URLの書き方」じゃない
RESTを一言で言うと、
「リソースを中心に、HTTPで会話する設計思想」
です。
よくある勘違いがこれ👇
- REST = URLを名詞にするルール ❌
- REST = GET/POST使い分けるやつ ❌
- REST = 設計の考え方 ⭕️
ここを勘違いすると、
一生"RESTっぽいAPI"を量産する人生が待ってます。
「RESTっぽいけどRESTじゃない」あるある3選
1. URL に動詞が入ってる問題
GET /getUser?id=1 ← これ
POST /createUser ← これ
POST /updateUserStatus ← これ全部アウト
なぜダメか?
「それ、RPC(Remote Procedure Call)っぽいですね」
って言われます。
翻訳:「関数呼び出しっぽくて、REST感ゼロっすね」
RESTでは「何をするか」じゃなくて
**「何に対して操作するか」**を主役にします。
2. 全部POSTで済ませる問題
POST /users/get ← なぜPOST...?
POST /users/update ← なぜPOST...?
POST /users/delete ← なぜPOST...?
動くけど、HTTPメソッドの意味を完全に無視してる。
こういうAPIを見ると、
レビュアーの目が死にます。
3. ステータスコードが全部200問題
// レスポンス
{
"status": 200,
"error": "User not found" ← いや404返せや
}
HTTPには便利なステータスコードがあるのに...
わざわざJSONに書くのは二度手間です。
RESTの基本:「リソース」が主役
RESTでは、操作したい**"モノ"**を主役にします。
例:ユーザー
/users ← ユーザー一覧というリソース
/users/1 ← ID=1のユーザーというリソース
/users/1/posts ← ユーザー1の投稿というリソース
これがリソースです。
そして、やりたいこと(取得・作成・更新・削除)は、
HTTPメソッドに任せるのがRESTの流儀。
HTTPメソッドは「動詞」担当
| やりたいこと | メソッド | 意味 |
|---|---|---|
| 見たい | GET | 読むだけ(副作用なし) |
| 作りたい | POST | 新しく作る |
| 丸ごと置き換えたい | PUT | 全体更新 |
| 一部だけ変えたい | PATCH | 部分更新 |
| 消したい | DELETE | 削除 |
つまり、こうなる👇
GET /users/1 ← ID=1のユーザーを取得
POST /users ← 新しいユーザーを作成
PATCH /users/1 ← ID=1のユーザーを部分更新
DELETE /users/1 ← ID=1のユーザーを削除
URLは名詞、メソッドが動詞。
これがRESTの基本形です。
めっちゃシンプルじゃないですか?
「POSTは作成専用」という罠
よくある誤解👇
「POST = create専用ですよね?」
半分正解、半分不正解。
POSTの本質は、
「サーバ側で新しい何かが生まれる操作」
です。
だから、こういうのも普通にPOST👇
POST /payments ← 決済処理(新しいトランザクションが生まれる)
POST /reports ← レポート生成(新しいレポートが生まれる)
POST /users/1/follow ← フォロー(新しいフォロー関係が生まれる)
「POST=作成だけ」と思ってると、
設計で詰みます。
ステータスコードで"サーバの気持ち"を伝える
REST APIで一気にレベルが分かれるのがここ。
よく使うやつ(これだけ覚えればOK)
| コード | 意味 | 使いどころ |
|---|---|---|
| 200 OK | 成功 | GET/PATCH/PUT成功時 |
| 201 Created | 作成成功 | POST成功時 |
| 204 No Content | 成功(返すものなし) | DELETE成功時 |
| 400 Bad Request | リクエストが変 | バリデーションエラー |
| 401 Unauthorized | 認証してない | ログインしてない |
| 403 Forbidden | 権限がない | ログインしてるけど権限不足 |
| 404 Not Found | 存在しない | リソースが見つからない |
| 409 Conflict | 状態が衝突 | 既に同じデータがある |
| 500 Internal Server Error | サーバ死亡 | 本当にヤバい時だけ |
ありがちな事故
バリデーションエラーなのに500返す
// ダメな例
POST /users
{
"name": "" // 空文字
}
// レスポンス
HTTP/1.1 500 Internal Server Error ← いや400だろ...
これやると、レビューで確実に刺されます。
RESTは「ステートレス」=サーバは記憶喪失
RESTでは、
「サーバは前回のリクエストを覚えない」
のが基本です。
つまり、
- セッションに依存しない
- 毎回トークン(JWTなど)を渡す
- リクエストだけ見て判断する
という設計になります。
なんで?
- スケールしやすい(複数サーバで状態共有不要)
- 障害に強い(1台落ちても大丈夫)
- 構成がシンプル
サーバが「あ、あなた前も来ましたね」って覚えてると、
スケールした時に地獄を見ます。
Spring Bootで見る「RESTらしいAPI」
コードで見るとこう👇
@RestController
@RequestMapping("/users")
public class UserController {
// ユーザー取得
@GetMapping("/{id}")
public UserResponse get(@PathVariable Long id) {
return userService.findById(id);
}
// ユーザー作成
@PostMapping
@ResponseStatus(HttpStatus.CREATED) // 201返す
public void create(@RequestBody @Valid CreateUserRequest request) {
userService.create(request);
}
// ユーザー更新
@PatchMapping("/{id}")
public void update(
@PathVariable Long id,
@RequestBody UpdateUserRequest request
) {
userService.update(id, request);
}
// ユーザー削除
@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT) // 204返す
public void delete(@PathVariable Long id) {
userService.delete(id);
}
}
これだけで「REST分かってる感」が出ます。
結局、RESTfulって何が嬉しいの?
正直なところ、
RESTを守らなくても、システムは動く
です。
でもRESTに寄せると、
-
APIが初見でも読める
→ GET /users/1 見たら「あ、ユーザー取得か」って分かる -
フロントと会話が早い
→ 「404返ってきたらユーザーいないってことね」で終わり -
設計レビューが楽
→ URL見れば何してるか分かる -
将来の変更に強い
→ リソース単位で分かれてるから影響範囲が明確
つまり、
**「チーム開発で効いてくる」**のがRESTです。
個人開発なら好きにしていい。
でもチームなら、共通言語としてのRESTは最強。
まとめ:RESTは"共通言語"
RESTは、
- 完璧に守らないとダメな宗教 ❌
- チームで会話しやすくするための共通言語 ⭕️
です。
もし次に、
「REST APIでお願いします」
と言われたら、
-
URLは名詞か? (
/getUserとか書いてない?) - 操作はHTTPメソッドか? (全部POSTになってない?)
- ステータスコードは正しいか? (全部200になってない?)
この3つだけ確認すれば、
もう"雰囲気REST"ではありません。
おわりに
RESTは、
分かった瞬間に急にシンプルに見えます。
そしてだいたい、
「あ、今までちょっとズレてたな...」
ってなります(自分もそうでした)。
この記事が、
誰かの「RESTってそういうことか!」になれば嬉しいです。
それでは、良いREST APIライフを!