URLに動詞を入れない — REST APIの設計

REST APIの設計。APIの設計書とデータの箱、操作を表す小さなカード。

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を消したとき、何を返すのが正しいのか

この記事でやること

  1. GET /api/tasks/:id — 1件だけ取る
  2. PUT と PATCH — 変更する
  3. DELETE — 消す
  4. curl で全部叩いて、返ってくる番号を確かめる

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
RESTAPIの設計の流儀のひとつ。「URLはモノ、メソッドが動詞」で組み立てる
リソースAPIが扱うモノ。この記事では「タスク」
エンドポイント呼び出す入口。GET /api/tasks のような組み合わせ1つ
パスパラメータURLの一部として渡す値。/api/tasks/3 の 3
冪等性(べきとうせい)同じ操作を何回やっても、結果が同じという性質

RESTは規格ではなく流儀です。 「こう書かないと動かない」ではなく、「こう揃えておくと、他人が読んで分かる」というだけのものです。 ただし世界中がこの流儀で書いているので、外れると読み手が毎回考えることになります。

URLはモノ、メソッドが動詞

RESTの中心は、これだけです。

URLには「何を」だけ書く。「どうするか」はHTTPメソッドで表す。

比べてみます。

やりたいこと❌ 動詞をURLに入れる✅ RESTらしい書き方
一覧を取るGET /api/getTasksGET /api/tasks
1件取るGET /api/getTask?id=3GET /api/tasks/3
追加するPOST /api/createTaskPOST /api/tasks
変更するPOST /api/updateTaskPUT /api/tasks/3
消すGET /api/deleteTask?id=3DELETE /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 で取れます。

立て直して叩きます。

bash
$ node --env-file=.env app.js
bash
$ curl -i -s http://localhost:3000/api/tasks/1
$ curl -i -s http://localhost:3000/api/tasks/9999

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: "更新できませんでした" });
  }
});
bash
$ curl -s -X PUT http://localhost:3000/api/tasks/1 \
    -H "Content-Type: application/json" \
    -d '{"title":"Linuxのコマンドを覚える","done":true}' | jq

PUT は「その中身に丸ごと置き換える」という意味です。だから title も done も両方必要です。

片方だけ送ると、どうなるか。

bash
$ curl -i -s -X PUT http://localhost:3000/api/tasks/1 \
    -H "Content-Type: application/json" -d '{"done":true}'
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: "更新できませんでした" });
  }
});
bash
$ curl -s -X PATCH http://localhost:3000/api/tasks/2 \
    -H "Content-Type: application/json" -d '{"done":false}' | jq

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: "削除できませんでした" });
  }
});
bash
$ curl -i -s -X DELETE http://localhost:3000/api/tasks/3
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回打つと、どうなるか

設計として決めておくべきことがあります。

bash
$ curl -i -s -X DELETE http://localhost:3000/api/tasks/3   # 1回目 → 204
$ curl -i -s -X DELETE http://localhost:3000/api/tasks/3   # 2回目 → 404

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 だけ性質が違う」と覚えてください。

全部まとめて叩く

完成したので、一周させます。

bash
$ curl -s -X POST http://localhost:3000/api/tasks \
    -H "Content-Type: application/json" -d '{"title":"RESTを覚える"}' | jq
$ curl -s http://localhost:3000/api/tasks | jq
$ curl -s http://localhost:3000/api/tasks/1 | jq
$ curl -s -X PATCH http://localhost:3000/api/tasks/1 \
    -H "Content-Type: application/json" -d '{"done":true}' | jq
$ curl -i -s -X DELETE http://localhost:3000/api/tasks/1

返ってくる番号を、必ず目で確認してください。

操作期待する番号
追加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 を返して気づけるようにしてある

後片づけ

この回で足したのはコードだけです。ポートもテーブルも増えていません。

サービスとして常駐させているなら、読み直させます。

bash
$ sudo systemctl restart myserver

~/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 は再送してはいけない
  • 列名を組み立てるのと、値を組み立てるのは別。 値は必ず ? に渡す

参考リンク


次に読む

この記事は 【第5段階】バックエンドとデータベース の 6 / 29 本目です。

記事
← 前の記事MySQLに別のサーバーから接続する — bind-addressとユーザーの接続元
→ 次の記事APIのエラー設計 — 4xxと5xxの分け方と、返す本文の決め方

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Backend›APIs
  • REST(リソースとメソッドの設計)
  • HTTP メソッドとステータスコード
  • Idempotency(冪等性)

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次