REST API設計とHTTPステータスコードの基礎を整理する

はじめに

Webアプリのバックエンドを作る際、多くの場合「REST API」という形式でフロントエンドとやり取りするエンドポイントを設計します。ここでは、REST APIの基本的な考え方と、レスポンスとして返すHTTPステータスコードの使い分けを整理します。

REST APIとは

REST(Representational State Transfer) は、Webサービスを設計する際の1つの指針(アーキテクチャスタイル)です。「リソース(データの塊)を、標準化されたクライアント/サーバー間のやり取りを通じて操作する」という考え方が基本になっています。

実務上は、REST本来の制約を厳密にすべて満たしていなくても、HTTPを使ったAPI全般が慣習的に「REST API」「RESTfulなAPI」と呼ばれることが多く、初学者としてはまず次の2つの考え方を押さえておくと実践的です。

1. URLは「リソース」を表す

REST的な設計では、URLのパスは「操作」ではなく「対象となるデータ(リソース)」を表すのが基本です。

❌ /getRecipes         （動詞を含んでいる）
✅ /recipes             （リソース名の名詞）

❌ /deleteRecipe?id=1
✅ /recipes/1           （DELETEメソッドと組み合わせる）

2. 「何をするか」はHTTPメソッドで表す

「操作の種類」は、URLではなくHTTPメソッドで表現します。代表的な組み合わせは次の通りです。

同じURL(/recipes/1)であっても、どのHTTPメソッドでアクセスするかによって意味が変わる、という点がポイントです。

HTTPステータスコードとは

HTTPステータスコードは、リクエストの処理結果をクライアントに伝えるための3桁の数値コードです。RFC 9110で定義されており、先頭の数字によって5つのクラスに分類されます。

よく使う2xx(成功)

よく使う4xx(クライアントエラー)

401と403は混同しやすいですが、「誰であるか自体が確認できていない(未ログイン)」場合は401、「本人であることは確認できているが、その操作の権限がない」場合は403、という使い分けが基本です。

よく使う5xx(サーバーエラー)

ステータスコードとレスポンスボディの役割分担

ステータスコードは「大まかな結果の種類」を伝える役割を持ちますが、「なぜ失敗したのか」「どのフィールドが問題だったのか」といった詳細な情報は、レスポンスボディ(JSON等)に含めるのが一般的です。

// 422のレスポンス例
{
  "detail": [
    {"loc": ["body", "email"], "msg": "value is not a valid email address"}
  ]
}

ステータスコードだけで判断せず、必要に応じてボディの内容も確認する、という設計がクライアント側にも求められます。

まとめ

参考

• HTTP response status codes - MDN Web Docs
• REST - Glossary - MDN Web Docs