HTTP APIは常に本文を返す必要がありますか？

HTTP API応答に関する何らかの標準はありますか？

この談話スレッドを読んだ後、私は疑問に思い始めました。私の仕事ではパブリックHTTP JSON APIを開発していますが、厳密に必要でない場合は何も返しません（たとえば、/ resource / {id}へのPUTは、OKまたは対応する4XXまたは5XXコードのときに200のみを返しますが、 JSON本体）

{"success":true}上記のリンクで説明したようなジェネリックを返す必要がありますか、それとも「void」ボディを返してすべてをhttp応答コードで処理しても大丈夫ですか？

PUTに関してですが、POSTにも適用されます。HTTPの仕様、それはあなたが記述されていることをシナリオに来るときセクション9は、ルール、あるいはアドバイス（SHOULD）にはほとんど空です。あなたの質問に関連する行は、最も密接にカバーされています：

新しいリソースが作成された場合、オリジンサーバーは201（Created）レスポンスを介してユーザーエージェントに通知しなければなりません。既存のリソースが変更された場合、200（OK）または204（No Content）応答コードのいずれかを送信して、要求が正常に完了したことを示す必要があります。

スリープ状態を失うとは思いませんが、応答にJSONのチャンクを追加することで何が得られるのでしょうか？ステータスコードで既に通知されているはずの応答が、あまり正確に繰り返されていないので（一括処理はやり過ぎかもしれません！）PUTが新しいオブジェクトを返した場合（PUTの意図どおり）201、オブジェクトを更新した場合は204を返します。

ちなみに、何も返さない場合は、200の代わりにAPIを使用して204を使用します。

RESTfulインターフェースのセットを開発していると仮定すると、それ自体に標準はないので、何をするにしても、それをよく文書化し、例を提供してください。すべては大丈夫です。

基本HTTP標準では、応答とともにドキュメントが返されることを義務付けていません。経済のために、HTTPステータスが必要なすべてを伝える場合、ボディは無駄になります。ただし、HTTPの上に構築され、新しいルールを追加する標準があります。

以下を指定するオープンJSON API標準があります。

• JSONオブジェクトは、すべてのJSON API 応答ドキュメントのルートに存在する必要があります。（斜体は、テキストを明確にするために追加したものを表します）

残念ながら、標準では空のドキュメントの表現方法が指定されておらず、作業中です。せいぜい私はそれをガイドラインとして使用したいと思います。

一部のアプリケーション（ElasticSearchなど）は完全なJSON APIを提供し、常にメタデータを持っているため、サーバーがデータをどのように管理しているかをよりよく把握できます。標準の応答オブジェクトは、リクエストの結果がエラーになった場合、影響を受けたノードの数など、インデックスの健全性について通知します。ElasticSearchはmimeタイプに「application / json」を使用するため、 jsonapi.org標準。

JQueryおよび同様のJavascriptフレームワークは、常にドキュメントがあることを前提としています。問題は、APIコンシューマーにどの程度のエラーチェックを強制するかです。要求のタイプに基づいてのみ拡張されるすべての応答の標準形式を考え出す場合、戻りドキュメントの必要性を満たし、APIコンシューマーによるデバッグを容易にすることができます。

ノー例えば、204の応答のために、私たちは、メッセージ本文を含めることはできません。{success | status | isSuccessful：true}は冗長です。

実際には（またはjqueryの以降のバージョンで言う必要があります）、application / jsonコンテンツタイプの空の応答はエラーを発生させます。私は、アプリケーション/ jsonであるため、有効なjsonボディを持たなければならないという議論を理解しています。したがって、application / jsonコンテンツタイプの空の応答は、有効なjsonである「null」または「{}」になります。

jqueryで機能する別の方法があります。それは、空の応答に対してapplication / jsonを返さないことです。text / plainなどを使用して、クライアントがそのタイプを処理できることを確認してください。

注：メッセージ本文の返送を明示的に禁止しているのは204のみです。私たちが見つけたのは、204を常に使用できるとは限らないことです。問題は、204応答のMSIEドロップ応答ヘッダーです。したがって、コンテンツとヘッダーがなく、これは悪いことです。多くがMSIEを使用しているため、200ステータスに変更する必要がありました。

いいえ、コードの一貫性に役立ちます。また、デバッグ目的にも適しています。また、ウェブサイトのメンテナンスにも大いに役立ちます。これを覚えておいてください：エラーコードはマシン用で、エラーメッセージは人間用です。そのため、応答本文を使用することをお勧めします。とにかく、その利点と比較して、そのマイナスの影響はごくわずかです（ネットワーク経由で送信される数バイト）。また、必要なときにメッセージ本文を書くのを忘れないようにすることもできます。

応答で単に成功ステータスを返すのではなく、httpエラーコードは成功またはエラーのみを通知します。応答自体を使用して、アプリケーション固有のエラーコードやエラーメッセージなどの詳細なエラー情報を追加するだけです。

PUT、PATCH、およびPOSTリクエストの場合、通常は状態を返し、空のレスポンスではなく、リクエストが適用された後のリソースの状態を返します。

単純にリソースを作成するのではなく、アクションを表すPOSTリクエスト（あまりRESTfulではありませんが、実際には便利です）を返します{}。そうすれば、クライアントは有効な応答を取得し、後で情報を追加しても壊れることはほとんどありません。

DELETEリクエストでは204を返し、空のボディがかなり一般的です。これは、後でリソースが存在しないため意味があります。

必要なものだけを返して+少し説明することをお勧めします。

たとえば、APIの使用方法に応じて、保存後に存在するオブジェクトのコピーを含めることができます。

したがって、{key：123}のPOSTは{key：123、foo： 'bar'}を返す可能性があります。

基本的な考え方は、オブジェクトを返してから再度照会する必要があるということです。

つまり、APIコンシューマーのオブジェクトを必要としないので、それを返す必要はありません。

POST PUTおよびPATCHで必要なオブジェクトが存在しない場合、受信側が簡単になるため、通常{success：true}などを返します。とは言っても、保存されたオブジェクトの表現を返すのは99％のほうが良いです。とにかくそれを必要としないことはめったになく、1回のリクエストですべてを送信してから2回で送信するのは「安い」です。

具体的には、ラボではステータスコードだけですべてを処理することが完全に見つかります。実際の世界では、APIの消費者があなたの言おうとしていることを簡単に理解できるように、冗長であってもデータを返す方がはるかに優れています。

200 {success：true}を返すと、人々は両方の方法でコードを書くことができます。

if response.code == 200
  do stuff
end

そして

if response.body.success
  do stuff
end

さらに、あなたの側でそれを行うのはそれほど難しくありません。

最後に、（poosの回答構造については申し訳ありませんが）パブリックJSON APIを提供することにより、使用方法に関する多くの制御をあきらめます。一部のクライアントは、異なるボディ（またはその欠如）またはステータスコードに対して異なる反応をする場合があります。