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ライフを!