コレクション、アイテム、動詞、RESTインターフェイスデザイン：POSTは何を返すべきですか？

Question

私はRESTインターフェースを設計していますが、挿入/更新/削除動詞が返されるべきかどうか（レスポンスの内容として）困惑しています。 api/invoicesでアクセス可能Invoiceエンティティのintefaceをし、考えてみましょう：

• GET /api/invoicesは、請求書のリストを返します
• GET /api/invoices/123戻っID 123
• POST /api/invoicesと請求書が（サーバー上で生成されたID）新しい請求書を追加し
• POST /api/invoices/123 IDを使用した請求書の更新123
• DELETE /api/invoices/123 IDを持つ請求書を削除します。123

最初の2つのメソッドが返すはずのものはかなりわかりますが、挿入/更新/削除の方法はどうですか？明らかな答えは、addは、新しく作成されたアイテム（GET/api/invoices/idとまったく同じ応答）を返さなければならないということです。updateは更新されたアイテムを返します（GETと同じです）。deleteは、空のコンテンツ）。これはすべて理にかなっており、合理的です。

しかし、私の問題は、Invoiceエンティティほど簡単ではないアイテムを検討するときに始まります。例えば、addリクエストは、アイテムを追加するだけでなく、実際には追加操作に関するいくつかの追加情報を返す必要があります。アイテムは受け入れられました（成功）、アイテムは重複しています（成功した情報）、アイテムは無視されました情報で成功、私は詳細にeneterしません）、項目は拒否された（失敗）。私の場合も、私が戻ってきたい追加情報があります。新しく追加された項目にバケツ用にあらかじめ設定された「応答」情報が壊れます。私はHTTPヘッダーのすべての余分な情報を帯域外情報の一種（200の範囲とカスタムヘッダーのような余分なステータスコードのようなもの）として置くことを考えましたが、ハックであり、 '応答'部分は実際にはアイテム自体。だから私はadd動詞は完全に新しいタイプ、追加情報（ステータス、応答、新しいアイテムのID、perhpas新しいアイテム全体）を含むアイテムを返すと考えています。それは確かに仕事を終わらせるが、私は前に持っていた素敵な対称性を見逃している。

これはよい習慣（「foo」というタイプのアイテムを追加するときはリターンが 'bar'タイプです）、または6ヶ月後に振り返って私の髪を引っ張るものですか？バッグの？私が 'fooの任意のアクセスが追加を含むfooを返す'と固執すれば、クライアントは実際に関心のある情報（すなわち '応答'）を取得するために 'add'操作の後に余分な呼び出しを行う必要があります。

Answer 1

ご返信はやや複雑です。インバウンドリクエストと一致しないはずです。 JSONを使用し、オブジェクトに加えていくつかの追加情報があります。

典型的なREPONSE：

[{ "ID": the generated ID, "TYPE": the actual class name, "OBJECT": { the object } }] 

POSTが作成されたオブジェクトを返す必要があります。余分な情報がある場合（これは良い考えではありません）、レスポンスメッセージにその情報を含めることができます。

PUTは更新結果を返す必要があります。

GETのように、DELETEはステータスを返すだけです。

ステータスの追加情報はハックではありません。そのため、ステータスコードはオープンエンドになっています。

項目が受け入れられた

• （成功） - ステータスが200 OK

• アイテムが重複（情報と成功）である - 私はあなたが上とを超えなければならない可能性どのような情報はわかりません最終的なオブジェクトが作成されましたが、これは20x - OK WITH INFOステータスの場所です。

• このアイテムは無視されました（情報で成功しましたが、詳細はわかりません） - これはあいまいです。私はそれを成功と呼ぶつもりはない、私はそれを40xと呼ぶだろう - 無視した。なぜあなたは詳細に行くことができない場合は、20倍 - 無視と呼ぶことができます。

• アイテムは拒否されました（失敗）。これは普通の古い40X REJECTEDメッセージです。

Answer 2

POSTリターンを考慮するためのオプションは、それが余分情報と、新しく作成されたオブジェクトへのリンクを返すことです。これは、GETが戻ってきて完全に別個のエンティティを返すことと同じものを返すことの間に素晴らしい中央線を走らせます。