URLに動詞を入れると、すぐ破綻します。URLはモノ、メソッドが動詞という原則で、変更と削除を足します。
前回: プロセスを止めても消えない場所 — MySQLとSQLの基本 作業場所はVMの中(Ubuntu)です。前回の
~/server/app.jsとappdbをそのまま使います。
ここまでで、こうなっています。
| できること | 使ったもの |
|---|---|
| 一覧を取る | GET /api/tasks |
| 追加する | POST /api/tasks |
残っているのは「変更」と「削除」です。 そして、それを足そうとした瞬間に、最初の分かれ道が来ます。
/api/deleteTask?id=3
こう書きたくなります。 分かりやすいからです。でも、そうしません。
DELETE /api/tasks/3
この回は、なぜこちらなのかという話です。
対象レベル: 初級〜中級 / 区分: 必修
この記事でわかること
- URLはモノ、メソッドが動詞という考え方(=RESTの中心)
PUTとPATCHの違い(全部置き換えるのか、一部だけか)- 同じ操作を2回打っても壊れないとはどういうことか(冪等性)
- 無いIDを消したとき、何を返すのが正しいのか
この記事でやること
GET /api/tasks/:id— 1件だけ取るPUTとPATCH— 変更するDELETE— 消すcurlで全部叩いて、返ってくる番号を確かめる
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| REST | APIの設計の流儀のひとつ。「URLはモノ、メソッドが動詞」で組み立てる |
| リソース | APIが扱うモノ。この記事では「タスク」 |
| エンドポイント | 呼び出す入口。GET /api/tasks のような組み合わせ1つ |
| パスパラメータ | URLの一部として渡す値。/api/tasks/3 の 3 |
| 冪等性(べきとうせい) | 同じ操作を何回やっても、結果が同じという性質 |
RESTは規格ではなく流儀です。 「こう書かないと動かない」ではなく、「こう揃えておくと、他人が読んで分かる」というだけのものです。 ただし世界中がこの流儀で書いているので、外れると読み手が毎回考えることになります。
URLはモノ、メソッドが動詞
RESTの中心は、これだけです。
URLには「何を」だけ書く。「どうするか」はHTTPメソッドで表す。
比べてみます。
| やりたいこと | ❌ 動詞をURLに入れる | ✅ RESTらしい書き方 |
|---|---|---|
| 一覧を取る | GET /api/getTasks | GET /api/tasks |
| 1件取る | GET /api/getTask?id=3 | GET /api/tasks/3 |
| 追加する | POST /api/createTask | POST /api/tasks |
| 変更する | POST /api/updateTask | PUT /api/tasks/3 |
| 消す | GET /api/deleteTask?id=3 | DELETE /api/tasks/3 |
左側でも動きます。 では何が困るのか。
① URLが無限に増える
動詞をURLに入れると、動作のぶんだけURLが増えます。 getTasks getTask createTask updateTask deleteTask completeTask uncompleteTask……。
右側は /api/tasks と /api/tasks/3 の2本しかありません。 動作はメソッドで分かれるので、URLは増えません。
② 一番危ないのは「GET で消せる」こと
左の最後の行を見てください。
GET /api/deleteTask?id=3
GET は「取ってくるだけ」の約束です。だから世の中のあらゆるものが、勝手に GET を叩きます。
- ブラウザは先読みする
- 検索エンジンのクローラはリンクを片っ端から開く
- チャットにURLを貼ると、プレビューのために開かれる
「一覧に貼ったURLを、Slackに貼ったら全部消えた」 は、実際に起こる事故です。
GETで状態を変えてはいけません。 これはRESTの流儀である以前に、HTTPの約束です。 開発者ツールの回の Network タブで、ページを開いただけで大量のGETが飛んでいたのを見たはずです。あれが全部「消す」だったら、と考えてください。
前回のコードに足していく
~/server/app.js の、app.post の下に足していきます。
① 1件だけ取る — GET /api/tasks/:id
app.get("/api/tasks/:id", async (req, res) => {
try {
const [rows] = await pool.query(
"SELECT id, title, done, created_at FROM tasks WHERE id = ?",
[req.params.id]
);
if (rows.length === 0) {
return res.status(404).json({ error: "そのタスクはありません" });
}
res.json(rows[0]);
} catch (err) {
console.error(err);
res.status(500).json({ error: "データベースに繋がりません" });
}
});
:id の部分が「何でもいい」という印です。入った値は req.params.id で取れます。
立て直して叩きます。
1件目は 200、2件目は 404 が返ります。
404と500を混ぜないでください。
番号 意味 例 404 そのモノが無い(利用者の指定が間違い) ID 9999 のタスクは存在しない 500 こちらが壊れている MySQLが落ちている 無いIDに 500 を返すと、監視のアラートが鳴り続けます。 「壊れている」と言っているからです。 逆にDBが落ちているのに 404 を返すと、誰も障害に気づけません。
② 全部置き換える — PUT
app.put("/api/tasks/:id", async (req, res) => {
const { title, done } = req.body;
if (typeof title !== "string" || title.trim() === "") {
return res.status(400).json({ error: "title は必須です" });
}
if (typeof done !== "boolean") {
return res.status(400).json({ error: "done は true か false で送ってください" });
}
try {
const [result] = await pool.query(
"UPDATE tasks SET title = ?, done = ? WHERE id = ?",
[title, done, req.params.id]
);
if (result.affectedRows === 0) {
return res.status(404).json({ error: "そのタスクはありません" });
}
const [rows] = await pool.query(
"SELECT id, title, done, created_at FROM tasks WHERE id = ?",
[req.params.id]
);
res.json(rows[0]);
} catch (err) {
console.error(err);
res.status(500).json({ error: "更新できませんでした" });
}
});
PUT は「その中身に丸ごと置き換える」という意味です。だから title も done も両方必要です。
片方だけ送ると、どうなるか。
HTTP/1.1 400 Bad Request
{"error":"title は必須です"}
これは正しい動きです。 「置き換える」と言っているのに中身が足りないので、断ります。
result.affectedRowsを見ているのが要点です。UPDATE ... WHERE id = 9999はエラーになりません。 「0行を書き換えた」という成功です。 だから「何行に効いたか」を自分で見ないと、無いIDへの更新を 200 で返してしまいます。
③ 一部だけ変える — PATCH
「完了にする」だけをやりたいのに、毎回 title も送るのは無駄です。 そのための PATCH です。
app.patch("/api/tasks/:id", async (req, res) => {
const sets = [];
const values = [];
if (typeof req.body.title === "string" && req.body.title.trim() !== "") {
sets.push("title = ?");
values.push(req.body.title);
}
if (typeof req.body.done === "boolean") {
sets.push("done = ?");
values.push(req.body.done);
}
if (sets.length === 0) {
return res.status(400).json({ error: "変更する項目がありません" });
}
values.push(req.params.id);
try {
const [result] = await pool.query(
`UPDATE tasks SET ${sets.join(", ")} WHERE id = ?`,
values
);
if (result.affectedRows === 0) {
return res.status(404).json({ error: "そのタスクはありません" });
}
const [rows] = await pool.query(
"SELECT id, title, done, created_at FROM tasks WHERE id = ?",
[req.params.id]
);
res.json(rows[0]);
} catch (err) {
console.error(err);
res.status(500).json({ error: "更新できませんでした" });
}
});
title を送らなくても通ります。
ここだけ SQL を文字列で組み立てています。 前回「文字列を繋げるな」と書いたのと矛盾して見えます。 繋げているのは「列の名前」だけで、利用者が入れた値は
?のままです。値はvaluesに入れて渡しています。 列の名前も利用者から受け取っていたら、それはSQLインジェクションです。 ここではtitleとdoneというこちらが決めた2つしか入らないので安全です。この区別を外すと、一瞬で穴になります。
| 意味 | 送るもの | |
|---|---|---|
PUT | 丸ごと置き換える | 全部の項目 |
PATCH | 一部だけ変える | 変えたい項目だけ |
④ 消す — DELETE
app.delete("/api/tasks/:id", async (req, res) => {
try {
const [result] = await pool.query("DELETE FROM tasks WHERE id = ?", [req.params.id]);
if (result.affectedRows === 0) {
return res.status(404).json({ error: "そのタスクはありません" });
}
res.status(204).end();
} catch (err) {
console.error(err);
res.status(500).json({ error: "削除できませんでした" });
}
});
HTTP/1.1 204 No Content
204 は「成功したが、返す中身は無い」です。消したものを返しても仕方ないので、本文を空にします。res.end() を使うのはそのためです(Express は 204 のとき、res.json() に渡した本文も自動で捨てます。捨てられるものを書かず、end() で終えるほうが意図がはっきりします)。
CORS の許可を増やす
メソッドを増やしたので、前回書いたCORSの許可も足します。 忘れると、ブラウザからは PUT と DELETE だけ通りません。
res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
APIの回でやったプリフライトが、ここで効いてきます。
PUTやDELETEは「単純なリクエスト」ではないので、必ず先にOPTIONSが飛びます。 そこで許していないメソッドは、本番のリクエストが送られる前に止まります。
同じ操作を2回打つと、どうなるか
設計として決めておくべきことがあります。
2回目は 404 です。 もう無いからです。
これは「同じ操作を2回やったのに、返事が違う」ということです。困るでしょうか。
困りません。そして、それは「壊れていない」からです。
冪等(べきとう)とは、「何回やっても、結果の状態が同じ」という意味です。返事が同じ、ではありません。 1回目のあとも2回目のあとも、「ID 3 は存在しない」という同じ状態です。だから
DELETEは冪等です。
メソッドごとに、こう決まっています。
| メソッド | 冪等か | 何回打っても |
|---|---|---|
GET | 冪等 | 何も変わらない |
POST | 冪等でない | 打つたびに1件ずつ増える |
PUT | 冪等 | 同じ中身に置き換わるだけ |
PATCH | 場合による | done = true なら冪等。「+1する」なら冪等でない |
DELETE | 冪等 | 1回目で消えて、あとは無いまま |
これが効くのは、通信が失敗したときです。
返事が返ってこなかったとき、もう一度送っていいのか。
・
PUT/DELETEなら、送っていい(何回打っても状態は同じ)
・POSTは送ってはいけない(二重登録になる)ネットの調子が悪いときに「送信」を2回押して同じ注文が2件入る、あれです。
POSTが冪等でないから起きます。 対策は、同じ操作を1回にまとめる印を持たせることですが、それは先の話です。いまは「POSTだけ性質が違う」と覚えてください。
全部まとめて叩く
完成したので、一周させます。
返ってくる番号を、必ず目で確認してください。
| 操作 | 期待する番号 |
|---|---|
| 追加 | 201 |
| 一覧・1件取得 | 200 |
| 変更 | 200 |
| 削除 | 204 |
| 無いIDに何かする | 404 |
| 中身がおかしい | 400 |
[スクリーンショット: 01_rest_一周.png] 上の5つを続けて実行し、201 → 200 → 200 → 200 → 204 と番号が並んでいる画面を撮ってください。-i を付けると番号が見えます。
設計で迷うところ
手が止まりやすい3つだけ書いておきます。
複数形か、単数形か
複数形で揃えます。 /api/tasks です。
/api/tasks が「タスクの集まり」、/api/tasks/3 が「その中の1つ」と読めます。単数形にすると、一覧のURLが不自然になります。
どちらでも動きますが、混ぜるのが一番よくありません。 /api/tasks と /api/user が並ぶと、毎回どちらか思い出せなくなります。
入れ子にするか
「あるユーザーのタスク一覧」は、こう書けます。
GET /api/users/5/tasks
2階層までにしてください。 3階層を超えると、URLが長くなるうえに、どこから読むのか分からなくなります。
GET /api/tasks?userId=5 ← こちらでもよい
「所属を表したいなら入れ子、絞り込みたいなら検索条件」が目安です。
バージョンを付けるか
/api/v1/tasks
外に公開するAPIなら付けます。 一度公開したAPIの形は、勝手に変えられないからです。使っている人のプログラムが動かなくなります。
自分だけが使うなら、いまは要りません。 付けるなら最初からで、あとから付けるのは大変です。
つまずいたところ
| 症状 | 原因 |
|---|---|
| 無いIDを更新したのに 200 が返る | affectedRows を見ていない。 UPDATE は0行でも成功する |
ブラウザから PUT / DELETE だけ通らない | Access-Control-Allow-Methods に足していない(プリフライトで止まる) |
DELETE で res.status(204).json(...) に渡したデータが返ってこない | 204 は本文を持てない。 Express が本文を捨てている。返さないなら res.status(204).end() |
req.params.id が文字列で困る | URLから来る値は必ず文字列。 数値として使うなら Number() する |
PATCH で何も変わらない | 送ったキーの綴り違い。sets.length === 0 で 400 を返して気づけるようにしてある |
後片づけ
この回で足したのはコードだけです。ポートもテーブルも増えていません。
サービスとして常駐させているなら、読み直させます。
~/server/とappdbは残してください。 次回、このAPIに「誰が使っているか」を持たせます(認証)。
まとめ
- URLはモノ、メソッドが動詞。
deleteTaskではなくDELETE /api/tasks/3 - 動詞をURLに入れると、URLが動作の数だけ増える。 RESTなら2本で足りる
GETで状態を変えない。 ブラウザもクローラもチャットのプレビューも、勝手にGETを叩くPUTは丸ごと置き換え、PATCHは一部だけ。 送るものが違うUPDATE/DELETEは0行でも成功する。affectedRowsを見ないと、無いIDに 200 を返す- 404 は「そのモノが無い」、500 は「こちらが壊れている」。 混ぜると障害に気づけなくなる
- 204 は「成功したが本文は無い」。 削除の返事に使う
- 冪等とは「何回やっても状態が同じ」。 返事が同じ、ではない
POSTは冪等でない(PATCHも書き方次第で冪等でなくなる)。 だから通信が失敗したとき、POSTは再送してはいけない- 列名を組み立てるのと、値を組み立てるのは別。 値は必ず
?に渡す
参考リンク
- roadmap.sh — Backend(APIs / REST の項目)
- roadmap.sh — API Design
- MDN — HTTP リクエストメソッド
- MDN — HTTP レスポンスステータスコード
- Express — ルーティング
次に読む
この記事は 【第5段階】バックエンドとデータベース の 6 / 29 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- REST(リソースとメソッドの設計)
- HTTP メソッドとステータスコード
- Idempotency(冪等性)
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント