[1] 201 (Created) は、 新たに資源が作成されたことを表す状態符号です。

[511] 例えば POST 要求によって新しい資源を作成することを求め、 鯖がその処理を成功させた場合には、鯖は 201 応答を返すことができます。この時 payload body には作成処理の結果や作成した資源の URL などを含めることができます。また Location: ヘッダーに作成した資源の URL を明記できます。

仕様書

意味

[514] 状態符号が 201 の応答は、要求が満たされ、 一つ以上の資源が新しく作られたことを示しています >>513。

[516] 当該応答の payload は、普通は作成された資源を説明したり、 リンクしていたりするものです >>513。

[515] 新たに作られた資源のうち主たるものは、 Location: があればその URL により、 なければ実効要求URLにより識別されます >>513。[517] 作られた資源をそのまま応答で返すわけではありません。 ただし Prefer: return も参照。

構文

[2] 201 応答は Location: 頭欄を使用できます。 Location: 欄本体には作成された資源を識別する URI を指定します。

[17] 指定されない場合は実効要求URLが識別することになる (>>515) ので、つまり要求の URL ということになります。

[18] 実世界の Web API 等での利用例を見るに、これは必ずしも従われていないようです。 Location: が省略されているからといって、作成されたものがその要求と同じ URL に存在しているとは限りません。

[19] 従って実装は PUT 要求の場合を除き、 Location: が明示的に指定されていないときは作成された資源の URL は不明とするべきです。

[3] 201 応答は ETag: 頭欄を使用できます。 ETag: 欄本体には作成された資源異体の実体札を指定します。

[16] LDP は Link: ...; rel=describedby によって作成された資源について記述することを認めています。

[4] 201 応答には実体本体を指定できます。 201 応答実体は、作成された資源についての情報を記述します。 具体的な書式は特に規定されていません。

[20] 実世界では空のこともありますし、「作成しました」のような自然言語文のこともありますし、 「201」のような簡単な文字列だけのこともあれば、 資源に関する何らかの機械可読なデータが提供されることもあります。

文脈

[417] 起源鯖は、 POST 要求の処理に成功して1つ以上の資源が作られた時には、 201 応答を送信するべきです。 >>412

[22] 実世界では必ずしもこの規定は従われていません。 POST の結果資源が作成されたとしても、 200 や 302 が返されることはよくあります。

[21] その場合、 Location: ヘッダーに作成された主たる資源の URL を含めるべきです。表現は要求の状態と新しい資源への参照を説明したものとするべきです。 >>412

[9] 207 応答の内部で 201 を使う時は、 Location: ヘッダーのかわりに location 要素を使います。

[510] 起源鯖は、対象資源が現在表現を持っておらず、 PUT によってその作成に成功した場合には、 201 を送信しなければなりません >>507。

[23] 予定地だけがあるところに実データが PUT で届けられた時、 201 を返すという意味です。

[8] LOCK 要求により新たな資源が作られた際は、 201 応答を返さなければなりません >>7。

[12] MKCOL 要求 >>11 や COPY 要求 >>13 や MOVE 要求 >>15 により新たな資源が作られた時は、201 応答を返します。

[14] COPY 要求 >>13 や MOVE 要求 >>15 に対する 207 応答内の status 要素では、 201 は使うべきではありません。

処理

[25] 201 を受信したクライアントがこれをどう処理するべきかは、 そのクライアントの性質によって異なります。 すべてのHTTPクライアントに共通する処理方法の規定はありません。

[24] Webブラウザーの navigate では payload が 200 の場合と同じ様に表示されることになります。 navigate

[512] 3xx 応答と同じ Location: ヘッダーを使ってはいますが、 (少なくても 3xx と同じ意味の) HTTPリダイレクトとは異なります。利用者エージェントは普通は Location: で指定された URL に自動的にアクセスすることはありません。

歴史

[418] RFC 1945 (HTTP/1.0); RFC 2068・2616 (HTTP/1.1) 10.2.2 201 Created

The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, {2068,2616} with the most specific URL URI for the resource given by a Location header field. {2616} The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server {1945} should {2068} MUST create the resource before {1945} using this Status-Code {2068} returning the 201 status code. If the action cannot be carried out immediately, {1945} the server must include in the response body a description of when the resource will be available; otherwise, the server {1945, 2068} should {2616} SHOULD respond with 202 {1945} (accepted) {2068} (Accepted) response instead.

要求は満たされまして、新しい資源が作られました。 新しく作られた資源は、応答の実体の中にある URI (群) によって参照することができます。 その資源を識別する一番の URI は Location 頭欄で指定します。 応答は、利用者や利用者エージェントが最適なものを選ぶことができるような、その資源の特徴と位置 (群) の一覧が含まれている実体を含むべきです。実体の書式は、 Content-Type 頭欄に指定した媒体型により規定されます。 起点鯖は、その資源を、 201 状態符号を返すよりも前に作成するべきです しなければなりません。 起点鯖がすぐに資源を作成できない場合には、その資源がいつ利用可能になるのかの説明を応答本体に含めなければなりません。そうしない場合には、 201 ではなしに 202 (受入れ) 応答を使って応答するべきです。

{1945} Of the methods defined by this specification, only POST can create a resource.

この仕様書で定義しました method の内では、 POST だけが資源を作成できます。

{2616} A 201 response MAY contain an ETag response header field indicating the current value of the entity tag for the requested variant just created, see section 14.19.

201 応答は、 ちょうど今作成するように要求された異体の実体札の現在値を示した ETag 応答頭欄を含めても構いません。

[6] RFC 2068 以前からある部分は資源を作成すると書いていますが、 RFC 2616 で追加された ETag: 欄の説明の部分では異体を作成と言っています。

201 はまったく新しい資源を作成した時に限らず、 既存の資源の新しい異体を作成した場合 (例えば HTML 版に加えて XHTML 版を作成した場合) にも使って良いのかもしれません。

[203] RFC 7252 - The Constrained Application Protocol (CoAP) ( ( 版)) http://tools.ietf.org/html/rfc7252#section-5.9.1.1

関連

[5] 201 応答を返し得る method には、 POST, PUT などがあります。

[10] 新しい資源が作成された時に 201 応答を使うことができますが、 201 を使う義務はありません。例えば自動的に作成した資源に利用者を移動させたいなら、 302 がより適切です。また作成が主たる処理ではなく副次的なものなら、 200 や 302 など他の状態符号がより適切かもしれません。

メモ