post

要求メソッド POST (HTTP)

[414] POST メソッドは、対象資源に対して引数となるデータを引き渡して、処理を求めるものです。

[415] フォーム提出などによって、 HTTP を通じて側の何らかのデータの追加、編集、削除、その他の操作を求めるために用いられます。

仕様書

意味

[413] POST メソッドは、要求に含まれる表現対象資源がその自身の意味 (semantics) に従って処理することを要求するものです >>412

[24] よく、単純な取得操作で副作用を持たない GET に対し、それ以外の何らかの変更操作一般を POST で行えると説明されます。

[25] 実際にどのような操作を行えるかは、そのサーバー資源の性質や実装に依存しており、 HTTP としては決められていません。資源を編集したり、削除したりできるかもしれませんし、 新しい資源を作成できるかもしれませんし、何もできないかもしれません。

[26] 本来 GET で十分な時でも、 URL が非常に長い (可能性がある) 場合に、 POST が代替として用いられることがあります。 要求URL の長さに仕様上の上限はありませんが、実装上の制限を設けることは認められていますし、 実用上極めて長い URL は扱いにくいため、かわりに payload body を使って引数を指定するというものです。

構文

[31] HTTPメソッド名は原則として大文字・小文字区別されますので、 POST はすべて大文字で書かなければなりません。

[32] ただし歴史的理由により、場合によってASCII大文字・小文字不区別になることがあります。 (複雑なので常に大文字を使うのが安全です。) HTTPメソッド


[8] POST 要求payload body には、処理の引数のような役割を果たすデータを含めるのが普通です。

[10] HTMLフォームの提出に使う場合は、次の MIME型payload body に含めます。

[11] Web API ではしばしば application/jsonXML MIME型が使われます。

[14] HTCPCPPOST 要求では、 payload bodyMIME型message/coffeepot でなければなりません >>15HTCPCP-TEA では message/teapot を使います >>16

[23] それ以外の任意の MIME型を用いることもできますが、 相互運用性は低くなります。

[22] 仕様上必須とはされていませんが、 Content-Length: ヘッダーがなければ 411 応答を返す実装が存在します。 クライアントは実用上 Content-Length: ヘッダーを指定する必要があります。

文脈

[9] POSTHTMLフォームの提出に使える要求メソッドの1つです。 HTML では他に GET も選べますが、 副作用を持つものは POST、持たないものは GET と使い分けるのが普通です。

[12] Web API でも広く使われています。

[13] HTCPCP では BREWPOST が等価 >>6, >>16 で、珈琲ポットへの制御命令に使われています。ただし POST非推奨とされています >>6, >>16

性質

[407] POST は、キャッシュ可能メソッドです >>406。 ただし、キャッシュ可能なのは、明示的に新鮮度の情報を含む場合のみです >>412

>>419 参照。
[418] POSTキャッシュは、広くは実装されていません >>412
[2] 実際に POST に対する応答キャッシュするべき場面がどれだけあるか、 キャッシュを実装する価値があるかは甚だ疑問です。
[21] PATCH メソッドPOST とほぼ同じ意味でキャッシュ可能です。 GETHEADキャッシュ可能であるというのとは若干意味が異なります。

[18] 書き込みロックの適用対象となります >>17

処理

[416] 起源鯖は、処理の結果によって適切な状態符号を選ぶことにより、 応答の意味を表します >>412

[417] 起源鯖は、処理に成功して1つ以上の資源が作られた時には、 201 応答を送信するべきですLocation: ヘッダーに作成された主たる資源URL を含めるべきです表現要求の状態と新しい資源への参照を説明したものとするべきです>>412

[419] 起源鯖は、 POST への応答キャッシュさせて以後の GET の処理で再利用できるようにしたい時は、 200 応答を送り、その Content-Location: ヘッダー実効要求URLと同じ値を設定することができます >>412

[420] 起源鯖は、処理の結果が既存の資源表現と等価である時には、 その URLLocation: ヘッダーに指定した 303 応答を送信することができます >>412

[421] 一般的には、 Webブラウザーで直接レンダリングすることを想定して HTML を返す場合には 302 を返してリダイレクトすることが多く、 JSON などを返す API の場合は 200 を返すことが多いようです。

[4] 200 を返すと Webブラウザーではその payload bodyレンダリングされますが、その状態で利用者再読み込みすると、 (Webブラウザーが確認ダイアログを表示するのが現在では一般的になっていますが) POST 要求が再送信されてしまいます。これは冪等ではなく、 普通は再投稿等の意図せぬ副作用を持ってしまうので、好ましくなく、 従って 302リダイレクトするのが一般的になっています。 (簡単な完了メッセージなどは 302 にせずに 200 でその場で返すこともあります。)

[422] 処理中にエラーが発生した場合には、その状況に応じて 400, 401, 403, 404, 405, 406, 500 などが返されることが多いですが、 状態符号を使い分けないアプリケーションでは、 200 でエラーメッセージを含む HTML文書が返されることもよくあります。

[5] クライアントPrefer: return によってどのような応答が返されることを望むか記述できます。 (しかしはそれに従う義務はありません。)

[7] HTCPCP 珈琲ポットは、 POSTBREW と等価として扱わなければなりません >>6, >>16

BREW を参照。

[20] WebDAV コレクションでも通常の資源と同じように任意の処理を実行できます >>19

関連

[27] 宗教上の理由で POST よりも PUTDELETEPATCH を好む人もいます。

[28] これらを使い分ける必要があるわけではありません。 フォームの提出プログラミング言語ライブラリー等の対応状況を考えると、 すべて POST で扱える方が便利です。

歴史

[408] RFC 1945 (HTTP/1.0) 8.3; RFC 2068・2616 (HTTP/1.1) 9.5 POST

The POST method is used to request that the {1945,2068} destination {2616} origin server accept the entity enclosed in the request as {1945,2068,2616} a new subordinate of {Errata} data to be processed by the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions:

POST 方式は、起源サーバーが要求に囲まれた実体Request-LineRequest-URI で識別される資源の新しい付随物で処理するデータとして受け入れることを要求するのに使います。 POST は次の機能を覆う統一方式とできるように設計されています。

  • {1945,2068} o {2616} - Annotation of existing resources;
  • o - Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;
  • o - Providing a block of data, such as the result of submitting a form [3] , to a data-handling process;
  • o - Extending a database through an append operation.

The actual function performed by the POST method is determined by the server and is usually dependent on the Request-URI. {1945,2068,2616} The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database. {Errata で削除}

POST}] 方式で行われる実際の機能はサーバーにより決定され、 通常 Request-URI に依存します。投稿された実体は、ファイルがそれを含むディレクトリに付随するとか、ニュース記事が投稿されたニュース組に付随するとか、記録がデータベースに藤生するのと同じように、その URI に付随します。

{1945} A successful POST does not require that the entity be created as a resource on the origin server or made accessible for future reference. That is, the The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 {1945} (ok) (OK) or 204 {1945} (no content) (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result.

;POST が成功したからといって、その実体が起源サーバー資源として作られたり、生来の参照で接続可能となる必要はありません。つまり、 POST 方式で行われる動作は結果として URI で識別できる資源にならないかもしれません。 この場合、応答が結果を説明する実体を含むか否かによって、 200 (了解) または 204 (無内容) が適切な応答符号です。

If a resource has been created on the origin server, the response {1945} should SHOULD be 201 {1945} (created) (Created) and contain an entity {1945} (preferably of type "text/html") which describes the status of the request and refers to the new resource, and a Location header (see section 14.30).

起源サーバーに資源が作られた場合は、応答は 201 (作成せし) とし、 要求の状態を説明して新しい資源を参照する実体と、 Locationを含むべきです

A valid Content-Length is required on all HTTP/1.0 POST requests. An HTTP/1.0 server should respond with a 400 (bad request) message if it cannot determine the length of the request message's content.

すべての HTTP/1.0 POST 要求で妥当な Content-Length が必要です。 HTTP/1.0 サーバーは、要求メッセージの内容の長さを決定できなければ 400 (悪い要求) メッセージで応答するべきです。

Applications must not cache responses to a POST request because the application has no way of knowing that the server would return an equivalent response on some future request.

応用は、サーバーが将来の要求でも同等の応答を返すということを知る方法が応答にはないので、 POST 要求への応答をキャッシュしてはなりません。

Responses to this method are not cacheable, unless the response includes appropriate Cache-Control or Expires header fields. However, the 303 (See Other) response can be used to direct the user agent to retrieve a cacheable resource.

この方式への応答は、応答が適切な Cache-Control 頭欄または Expires 頭欄を含んでいない限りキャッシュ可能ではありません。 しかし、利用者エージェントがキャッシュ可能資源を取り出すように指向するために 303 (他を見よ) 応答を使えます。

POST requests must MUST obey the message transmission requirements set out in section 8.2.

POST 要求は8.2節のメッセージ転送要件に従わなければなりません

See section 15.1.3 for security considerations.

安全性について15.1.3節を参照。

[409] Errata の変更事由

The description of POST was broadened over time, and is not clear.

POST の説明は時間と共に広がり、明確ではありません。

[410] RFC 2295 (HTTP 透過内容折衝) 12.2 Negotiation on transactions other than GET and HEAD

[1]

If a resource is transparently negotiable, this only has an impact on the GET and HEAD transactions on the resource. It is not possible (under this specification) to do transparent content negotiation on the direct result of a POST request.

資源が透過折衝可能であるときには、これはその資源の GET 及び HEAD の処理にのみ影響します。 (この仕様書では) POST 要求の直接の結果について透過内容折衝することは不可能です。

However, a POST request can return an unnegotiated 303 (See Other) response which causes the user agent to do a GET request on a second resource. This second resource could then use transparent content negotiation to return an appropriate final response. The figure below illustrates this.

しかし、 POST 要求は利用者エージェントに2番目の資源に GET 要求を行わせる折衝しない 303 (他を見よ) 応答を返すことが出来ます。 この2番目の応答の方は透過内容折衝を使って適当な最終応答を返すことができます。 次の図はこれを図示しています。

      Server ______ proxy ______ proxy ______ user
      x.org         cache        cache        agent
        < -------------------------------------
        |     POST http://x.org/cgi/submit
        |     <form contents in request body>
        |
        -------------------------------------- >
              303 See Other                    |
              Location: http://x.org/result/OK |
                                               |
        < -------------------------------------
        |     GET http://x.org/result/OK
        |      small Accept- headers
        |
      able to choose on
      behalf of user agent
        |
         ------------------------------------- >
              choice response with             |
              ..result/OK.nl variant           |
                                           displays OK.nl

See the HTTP/1.1 specification [1] for details on the 303 (See Other) status code. Note that this status code is not understood by some HTTP/1.0 clients.

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

メモ

[401] POSTリクエストをリダイレクトするとGETされる?POSTされる? - はこべにっき# ( 版) http://d.hatena.ne.jp/hakobe932/20090707/1246985195

[402] Extra CRLF Character Is Added to a POST Request That Is Sent to an HTTP 1.1 Server ( ( 版)) http://support.microsoft.com/kb/823099/en-us

[403] Apache HTTP Server Project ( ( 版)) http://httpd.apache.org/docs/1.3/misc/known_client_problems.html#trailing-crlf

[404] Apache HTTP Server Project ( ( 版)) http://httpd.apache.org/docs/1.3/misc/known_client_problems.html#no-content-length

[501] tus resumable upload protocol ( ( 版)) http://tus.io/protocols/resumable-upload.html#6-1-3-1

[29] RFC 8144 - Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV) () https://tools.ietf.org/html/rfc8144#section-3.1

[30] Google ウェブマスター向け公式ブログ: より多くの有益なコンテンツを検索結果に: クローラが POST リクエストにも対応しました () https://webmaster-ja.googleblog.com/2012/01/post.html