【入門編】 HTTPステータスコード204(No Content)の役割 – Web APIアーキテクチャ・データ連携実践ガイド

「お返事、空っぽでいいんです」― HTTP 204 No Content が教えてくれる、API設計の美学

エンジニアの皆さん、こんにちは！ネットワークの深淵を愛するインフラアーキテクトです。

API開発をしていると、必ず出会うのが「データを更新したとき、何を返せばいいの？」という悩み。特に、Web APIの設計において「RESTの原則」を意識し始めると、ステータスコードの選択はまるでパズルのピースをはめるような楽しさがありますよね。

今日は、そんな中でも少し控えめで、でも実はすごく「気が利く」存在、204 No Content についてお話ししましょう。

—

郵便配達でイメージしてみる「204 No Content」

まずは、ネットワークの小難しい話は一度置いておいて、身近な「郵便」に例えてみましょう。

あなたが誰かに手紙を送り、「この書類、もう不要だからシュレッダーにかけておいて！」と頼んだとします。相手は快く引き受けてくれて、シュレッダーを完了させました。

さて、このとき相手はあなたに何と返事をすべきでしょうか？

「了解！シュレッダーしたよ」という報告書をわざわざ封筒に入れて送り返す？
「承りました」と一言だけ口頭で伝える？

もし、いちいち「シュレッダー完了報告書」という中身のない紙を返送されても、受け取るあなたは「あ、そう。で？」となってしまいますよね。「完了したことが分かれば、中身は空っぽで十分！」という場面、まさにこれが 204 No Content の世界です。

—

なぜ「空っぽ」が美しいのか？

Web APIの世界では、200 OK を返せばとりあえず動くかもしれません。でも、200 OK は「ここにデータがあるよ！」というサインです。もし、クライアント（アプリ側）が「何かデータが来るはずだ」と身構えているのに、サーバー側が中身を返さないのは、少し不親切ですよね。

204 No Content を使うことには、こんなメリットがあります。

1. 通信量の節約: 不要なボディ（中身）を返さないので、帯域を無駄にしません。
2. ブラウザの賢い挙動: 204 を受け取ったブラウザやフロントエンドは、「お、中身はないんだな」と判断して、現在の画面を無理に更新したり、空のデータを探しに行ったりといった無駄な処理を省けます。
3. セマンティクス（意味論）の正しさ: 「リクエストは成功したけれど、返すべきデータはない」というステータスを明確に示すことで、コードを読み解く他のエンジニアへの「仕様書」のような役割を果たします。

—

実践！コードで見る DELETE の作法

例えば、ユーザー情報を削除する API を設計しているとしましょう。

Python (Flask) での例

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/users/<int:user_id>', methods=['DELETE'])
def delete_user(user_id):
    # ここでデータベースからユーザーを削除する処理を想定
    # success = db.delete(user_id)
    
    # 削除に成功したなら、204 No Content を返す
    # ボディは空で、ステータスコードだけを返します
    return '', 204

curl コマンドで確認してみる

ターミナルからリクエストを投げると、その挙動の軽快さがよく分かります。

# -i オプションでヘッダー情報を見てみましょう
curl -i -X DELETE http://api.example.com/users/123

# レスポンス結果のイメージ:
# HTTP/1.1 204 No Content
# Date: Wed, 25 Oct 2023 10:00:00 GMT
# Server: nginx/1.18.0
# (ここにボディは表示されません)

見事に 204 だけが返ってきましたね。余計な文字列や JSON が一切ない、この潔さ。まさに「スマートな設計」の証です。

—

気をつけてほしい「落とし穴」

一つだけ注意点があります。204 はあくまで「成功」の証です。もし、削除しようとしたユーザーIDが最初から存在しなかった場合は、204 ではなく 404 Not Found を返すのが正しいマナーです。

204 No Content: 「指示通り消しました。報告する中身はありません！」
404 Not Found: 「消そうと思ったけど、そもそも対象が見当たりませんでした…」

この使い分けが、あなたの書く API をぐっとプロフェッショナルなものに変えてくれます。

—

まとめ：一歩ずつ、美しいネットワークを目指して

ネットワークの深淵を覗くと、こうした小さなステータスコード一つひとつに、先人たちの「いかに効率よく、いかに誤解なく通信するか」という知恵が詰まっています。

最初は「200 OK 以外を使うのって怖そうだな」と思うかもしれません。ですが、204 No Content を使いこなすことは、クライアントに対する「配慮」そのものです。

皆さんの API が、無駄なく、かつ意図が明確な美しいエンドポイントになることを願っています。また何か疑問があれば、いつでも聞いてくださいね。それでは、素敵な開発ライフを！