REST APIを設計・利用する上で、ステータスコードの正しい使い分けは非常に重要です。
その中でも201（Created）は、新しいリソースの作成が成功した際に返すべきコードとして定義されており、200（OK）との違いを正確に理解しておくことが高品質なAPI設計の基本となります。
本記事では201の意味・使い方・設計上のポイントを詳しく解説していきます。
ステータスコード201とは？Createdレスポンスの結論
それではまず、ステータスコード201の基本的な定義と意味について解説していきます。
ステータスコード201（Created）とは、HTTPリクエストが成功し、その結果として新しいリソースが作成されたことを示す2xx系のレスポンスコードです。
RFC 7231にて定義されており、リクエストが完了し、1つ以上の新しいリソースが作成された場合に使用するとされています。
201は主にPOSTリクエストやPUTリクエストに対するレスポンスとして使用されます。
| コード | 名称 | 主な用途 |
|---|---|---|
| 200 | OK | リクエスト成功（汎用） |
| 201 | Created | 新規リソースの作成成功 |
| 204 | No Content | 成功だがレスポンスボディなし |
200（OK）はリクエストが成功した場合の汎用コードですが、新しいリソースが作成された場合は200ではなく201を返すことが、RESTful APIの設計原則として推奨されています。
201レスポンスのLocationヘッダー
201レスポンスには、作成されたリソースのURLをLocationヘッダーに含めることが強く推奨されています。
これにより、クライアントは作成されたリソースにすぐアクセスできるようになります。
201レスポンスのヘッダー例
HTTP/1.1 201 Created
Location: https://api.example.com/users/12345
Content-Type: application/json
Locationヘッダーを省略することも仕様上は許容されていますが、クライアントの利便性を考えると設定することがベストプラクティスです。
201レスポンスのボディ構成
201レスポンスのボディには、作成されたリソースの情報を含めることが一般的です。
サーバーが自動採番したIDや作成日時など、クライアントが送信していないが必要となる情報を含めることで、クライアントがすぐに作成リソースを活用できる状態になります。
ボディを含めることによってクライアントがリソース取得のための追加リクエストを省けるため、APIの効率も向上します。
201が使用される典型的なシーン
続いては、201レスポンスが実際に使用される典型的なシーンを確認していきます。
ユーザー登録とデータ作成
最もよく見られる201の使用シーンが、ユーザー登録などの新規データ作成です。
ユーザー情報をPOSTリクエストで送信し、サーバー側でユーザーレコードが作成された場合に201を返します。
作成されたユーザーのIDや作成日時をレスポンスボディに含めることで、クライアントはすぐに新ユーザーの情報を活用できます。
ファイルアップロードとリソース生成
ファイルのアップロードによって新しいリソースが生成される場合も201が適切です。
画像ファイルをアップロードしてストレージに保存された際、生成されたファイルのURLをLocationヘッダーとレスポンスボディに含めて返すのが一般的な設計です。
バッチ処理での複数リソース作成
複数のリソースを一括で作成するバッチ処理においても201は使用されます。
ただし、複数リソースが作成される場合はLocationヘッダーの扱いが複雑になるため、作成されたすべてのリソース情報をレスポンスボディに含める設計が採られることが多いでしょう。
| シーン | リクエスト | レスポンス |
|---|---|---|
| ユーザー登録 | POST /users | 201 + 作成ユーザー情報 |
| 記事投稿 | POST /articles | 201 + 作成記事情報 |
| ファイルアップロード | POST /files | 201 + ファイルURL |
| 注文作成 | POST /orders | 201 + 注文ID・詳細 |
201の設計上の注意点とベストプラクティス
続いては、201を使用したAPI設計における注意点とベストプラクティスを確認していきます。
200との使い分けの徹底
APIの一貫性を保つために、200と201の使い分けを徹底することが重要です。
既存リソースの取得や更新が成功した場合は200を使用し、新規リソースが作成された場合は必ず201を使用するというルールを設けることで、クライアント開発者がレスポンスコードから操作結果を直感的に把握できるようになります。
冪等性の考慮
PUTリクエストで201を返す場合は冪等性の考慮が必要です。
冪等性とは、同じリクエストを複数回実行しても結果が変わらない性質を指します。
PUTで同一リソースを作成しようとした場合、初回は201、2回目以降は200を返すという設計が一般的でしょう。
エラーとの組み合わせを避ける
201はあくまでリソース作成の「成功」を示すコードです。
部分的な成功や警告がある場合でも、201を返しつつレスポンスボディにエラー情報を混在させる設計は避けるべきでしょう。
成功は201で明確に示し、失敗はそれぞれ適切なエラーコード（422・400など）で返すという一貫した設計が求められます。
まとめ
本記事では、ステータスコード201（Created）の意味・使い方・設計上のポイントについて解説しました。
201はRESTful APIにおいて新しいリソースが作成された際に返すべきコードであり、200との使い分けを正確に行うことがAPI品質向上の基礎となります。
Locationヘッダーの設定・レスポンスボディへの作成リソース情報の包含・200との明確な使い分けを意識することで、クライアント開発者にとって使いやすく、意味のある明確なAPIを設計できます。
ステータスコードの正しい理解と活用を通じて、高品質なAPI開発を目指していきましょう。
