ステータスコードの選び方

このレッスンでは、操作の種類と結果の状況から、返すべき HTTP ステータスコードを決められるようになります。

まず 3 つの階層で考える

ステータスコードは 3 桁の数字ですが、意味を決めているのは先頭の 1 桁です。

この分類を間違えないだけで、API の使い勝手はかなり良くなります。クライアントが直せる問題なのか、直せない問題なのかを数字で伝えるのが本質です。

よく使う 9 つ

混同しやすい組み合わせ

200 と 201 — 作成が成功したときは 201 を返します。200 でも動きますが、201 には「新しいリソースができた」という追加の情報があります。あわせて Location ヘッダで場所を伝えるのが定石です。

200 と 204 — 削除が成功したときに返すものがないなら 204 が適切です。空の JSON を本文にして 200 を返すより意図がはっきりします。

401 と 403 — この 2 つは「誰か分からない」と「誰かは分かるが許されていない」の違いです。トークンが無い、または期限切れなら 401、ログイン済みの一般利用者が管理者専用の操作を叩いたなら 403 です。401 を返すということは、認証をやり直せば通るかもしれないという意味になります。

404 と 403 — 存在するリソースへの権限が無いとき、403 ではなくあえて 404 を返す設計もあります。403 だと「そこに何かはある」ことが漏れてしまうためです。どちらが正しいという話ではなく、情報を隠したいかどうかで選びます。

400 と 409 — 形式がおかしいのは 400 です。形式は正しいが今の状態と衝突するのが 409 です。メールアドレスの形が壊れているなら 400、形は正しいが既に登録済みなら 409 になります。

500 を返してはいけない場面 — 入力が悪くて落ちたのに 500 を返してしまうと、クライアントは自分に直せるものだと気づけません。想定できる失敗はすべて 4xx として明示し、500 は本当に想定外のものだけに残します。

Spring での書き方

@ResponseStatus で固定のコードを宣言できます。状況によってコードを変えたい場合は、次のレッスンで扱う ResponseEntity を使います。

演習で確かめます

Spring では @ResponseStatus や ResponseEntity が「決めたコードを実際に返す」部分を引き受けてくれますが、どのコードを返すかを決めるのは常に自分の仕事です。ここではその判断そのものを関数にします。操作の種類と結果の状況を受け取り、返すべきステータスコードを決めてください。

1. outcome が ok 以外のときは action を見ずに、invalid は 400、unauthenticated は 401、forbidden は 403、missing は 404、conflict は 409、error は 500 を返すこと
2. outcome が ok のときだけ action を見て、create は 201、delete は 204、それ以外は 200 を返すこと
3. 未知の outcome は 500 を返すこと