💨
POSTリクエストで204を返してもいいの？空のJSONを返すときのベストプラクティス
※本記事は、ChatGPTとの対話をもとに生成AIを活用して執筆していますが、全体の構成と主張は筆者自身の考えによるものです。
API設計をしていると、「この処理のレスポンスってどのステータスコードが適切なんだろう？」と迷うことは少なくありません。今回は、実務の中で私自身が少し悩んだことのある、「POSTリクエストで204を返してもいいのか？」「空のJSON（{}）を返すときのステータスコードは？」というトピックについて、自分なりに整理してみた内容を共有します。
POSTで204 No Contentは「あり」？
私の考えとしては、POSTで204を返すのは問題ないと思っています。ただし、使いどころには少し注意が必要だと感じています。
✅ 204を使って良さそうなケース
204は「リクエストは成功したが、返すコンテンツがない」ことを表すので、以下のような場合に自然かなと思います。
- ログ記録など、レスポンス不要なAPI
- セッション延長など、状態更新だけ行うAPI
- クライアントがレスポンスボディを特に必要としていないケース
たとえば、以下のようなAPIを想定してみます。
POST /api/log-event
このAPIがリクエストされたイベントをサーバーに記録するだけであれば、レスポンスを省略して204を返すのもアリだと思います。
⚠️ 204は避けたほうが良さそうなケース
一方で、次のような場合には204は向いていません。
-
新しいリソースを作成する場合
→201 Createdを返し、LocationヘッダーでリソースのURLを示す方が意図が伝わりやすいと思います。 -
レスポンスボディを返したい場合
→204はレスポンスボディを含めてはいけない仕様なので、JSONやテキストを返すなら200 OKを使うのが適切でしょう。
空のオブジェクト {} を返すときのステータスコードは？
空のJSONオブジェクト（{}）を返すときは、 200 OKを使うのが自然 だと思います。
理由
-
204 No Contentは仕様上、レスポンスボディを含めてはいけないため、{}を返すのはNGです。 -
{}は「空」ではあるものの、有効なJSONなので、ある種の構造や意味を持ったレスポンスとして解釈されることもあります。 - クライアントが
Content-Type: application/jsonを期待している場面では、明示的に空のJSONを返すことで一貫性が保てます。
状況別ステータスコードまとめ
| シナリオ | ステータスコード | 補足 |
|---|---|---|
| レスポンス不要 | 204 No Content |
ボディを含めないこと |
| 空のJSONを返す | 200 OK |
{} や [] はOK |
| 新しいリソースを作成 | 201 Created |
Locationヘッダーの設定が望ましい |
| 入力エラー | 400 Bad Request |
バリデーション結果を含めることが多い |
まとめ
ステータスコードの選定は、APIの利用者の体験や理解にも影響を与えるポイントです。
私自身、「とりあえず200でいいか」と思っていた時期もありましたが、状況に応じた使い分けを意識することで、より意図の伝わるAPI設計ができると感じています。
今回の話はあくまで私の経験に基づいたものなので、プロジェクトの方針やチームの慣習に合わせて柔軟に考えていただければと思います。
Discussion