REST APIエラーが良い習慣を返す[終了]

REST APIからエラーが返されるようになると、良い習慣に関するガイダンスを探しています。私は新しいAPIに取り組んでいるので、今はどの方向にでも進むことができます。現在のコンテンツタイプはXMLですが、将来はJSONをサポートする予定です。

たとえば、クライアントが新しいリソースを追加しようとしたが、ストレージクォータを超えたなど、いくつかのエラーケースを追加しています。HTTPステータスコード（認証は401、承認は403、プレーンなリクエストURIは404）を使用して、特定のエラーケースをすでに処理しています。祝福されたHTTPエラーコードを調べましたが、アプリケーション固有のエラーを報告するのに適切な範囲である400〜417の範囲はありません。したがって、最初は200 OKと特定のXMLペイロードでアプリケーションエラーを返したくなりました（つまり、さらに料金を払えば、必要なストレージを取得できます）。ホラーに肩をすくめる）。その上、エラーレスポンスを別個のケースに分割しているような気がします。いくつかはhttpステータスコードドリブンで、他はコンテンツドリブンです。

では、業界の推奨事項は何ですか？グッドプラクティス（理由を説明してください！）と、クライアントの視点から、REST APIでどのようなエラー処理を行うと、クライアントコードの処理が容易になりますか？

したがって、最初は200 OKと特定のXMLペイロードでアプリケーションエラーを返したくなりました（つまり、さらに料金を払えば、必要なストレージを取得できます）。ホラーに肩をすくめる）。

リクエストに問題がない限り、200を返しません。よりRFC2616、200件の手段は、「要求が成功しました。」

（何らかの理由で）クライアントのストレージクォータを超えた場合、403（禁止）を返します。

サーバーはリクエストを理解しましたが、リクエストの実行を拒否しています。承認は役に立たず、リクエストは繰り返されるべきではありません。リクエストメソッドがHEADではなく、サーバーがリクエストが実行されなかった理由を公開したい場合は、エンティティで拒否の理由を説明する必要があります。サーバーがこの情報をクライアントに提供したくない場合は、代わりにステータスコード404（見つかりません）を使用できます。

これは、要求は問題なかったが、失敗したことをクライアントに伝えます（200では実行できないもの）。これにより、応答本文で問題（およびその解決策）を説明する機会も得られます。

他にどのような具体的なエラー状態を考えましたか？

APIの正しいHTTPエラーコードを選択するための優れたリソース：http : //www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

記事からの抜粋：

どこから始めれば：

2XX / 3XX：

4XX：

5XX：

主な選択は、HTTPステータスコードをREST APIの一部として扱うかどうかです。

どちらの方法でも問題なく機能します。厳密に言うと、RESTのアイデアの1つは、HTTPステータスコードをAPIの一部として使用することです（操作が成功した場合は200または201を返し、さまざまなエラーケースに応じて4xxまたは5xxを返します）。 、RESTポリスはありません。あなたがやりたいことができます。私は、「RESTful」と呼ばれる非常に悪質な非REST APIを見てきました。

この時点（2015年8月）では、APIの一部としてHTTPステータスコードを使用することをお勧めします。フレームワークを使用すると、以前よりもはるかに簡単に戻りコードを確認できるようになりました。特に、これまでよりも200以外のリターンケースと200以外の応答の本文を確認するのが簡単になりました。

HTTPステータスコードはAPIの一部です

1. エラー条件に適合する4xxコードを慎重に選択する必要があります。サブコードと説明コメントを含むペイロードとして、rest、xml、または平文メッセージを含めることができます。

2. クライアントは、HTTPレベルのステータスコードを取得できるソフトウェアフレームワークを使用する必要があります。通常は実行可能であり、必ずしも単純ではありません。

3. クライアントは、通信エラーを示すHTTPステータスコードと、アプリケーションレベルの問題を示す独自のステータスコードを区別する必要があります。

HTTPステータスコードはAPIの一部ではありません

1. アプリがリクエストを受け取って応答した場合、HTTPステータスコードは常に200になります（成功とエラーの両方のケース）。

2. すべての応答には、「エンベロープ」または「ヘッダー」情報が含まれている必要があります。通常は次のようなものです：

   エンベロープバー：1.0
   ステータス：＃好きなコードを使用してください。成功のためにコードを予約します。
   msg： "ok"＃コードを反映する人間の文字列。デバッグに役立ちます。
   data：...＃応答のデータ（存在する場合）。

3. 応答のステータスは常に同じ場所にあり（サブコードは不要）、コードに制限がなく、HTTPレベルのステータスコードをフェッチする必要がないため、この方法はクライアントにとってより簡単になります。

これは同様のアイデアを持つ投稿です：http : //yuiblog.com/blog/2008/10/15/datatable-260-part-one/

主な問題：

1. 必要に応じて後でAPIのセマンティクスを変更できるように、必ずバージョン番号を含めてください。

2. 資料...

HTTP / 1.1 RFCで定義されているものよりも多くのステータスコードがあることに注意してください。IANAレジストリはhttp://www.iana.org/assignments/http-status-codesにあります。あなたがステータスコード507に言及した場合、正しいように聞こえます。

他の人が指摘したように、エラーコードに応答エンティティを含めることは完全に許容されます。

5xxエラーはサーバー側であることを覚えておいてください。別名クライアントは、要求を通過させるために要求に何も変更できません。クライアントのクォータを超えた場合、それは間違いなくサーバーエラーではないため、5xxは回避する必要があります。

エラーには2種類あります。アプリケーションエラーとHTTPエラー。HTTPエラーは、AJAXハンドラーに問題がないことを知らせるためのもので、他の目的には使用しないでください。

5xx サーバーエラー

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx成功

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

ただし、アプリケーションエラーをどのように設計するかは実際にはあなた次第です。たとえば、スタックオーバーフローはresponse、dataおよびmessageプロパティを持つオブジェクトを送信します。私が信じる応答には、操作が成功したかどうか（通常は書き込み操作の場合）が含まれているか、trueまたはfalse示されています。データにはペイロード（通常は読み取り操作用）が含まれ、メッセージには追加のメタデータまたは有用なメッセージ（responseisの場合のエラーメッセージなど）が含まれますfalse。

私はこれがパーティーに非常に遅れていることを知っていますが、現在、2013年には、一般的な分散（RESTful）方式でのエラー処理をカバーするメディアタイプがいくつかあります。「vnd.error」、application / vnd.error + json（https://github.com/blongden/vnd.error）および「HTTP APIの問題の詳細」、application / problem + json（https：// tools。 ietf.org/html/draft-nottingham-http-problem-05）。

同意した。RESTの基本的な考え方は、Webインフラストラクチャを使用することです。HTTPステータスコードは、HTTPペイロードを増やすことなく、パーティが互いに通信できるようにするメッセージングフレームワークです。それらはすでに応答のステータスを伝える確立されたユニバーサルコードであるため、真にRESTfulであるためには、アプリケーションはこのフレームワークを使用して応答ステータスを通信する必要があります。

HTTP 200エンベロープでエラー応答を送信することは誤解を招くものであり、クライアント（APIコンシューマー）がメッセージを解析するように強制します。これはおそらく非標準的な方法または独自の方法によるものです。これも効率的ではありません。「実際の」応答ステータスを理解するために、クライアントに毎回HTTPペイロードを解析させる必要があります。これにより、処理が増加し、レイテンシが追加され、クライアントがミスをする環境が作成されます。

既存の「ベストプラクティス」に基づいてAPIをモデル化するのがよいでしょう。たとえば、Twitterがエラーコードを処理する方法を次に示します https://developer.twitter.com/en/docs/basics/response-codes

プロトコルのセマンティクスに固執してください。成功した応答には2xxを使用し、エラー応答には4xx、5xxを使用します-ビジネスの例外などです。応答に2xxを使用することがプロトコルの意図されたユースケースであった場合、そもそも他のステータスコードはありません。

アプリケーションエラーの場合も、5xxエラーを忘れないでください。

この場合、409（競合）はどうですか？これは、ユーザーが格納されたリソースを削除することで問題を修正できることを前提としています。

それ以外の場合は、507（完全に標準ではない）でも機能する可能性があります。エラーに200を使用しない限り、200は使用しません。

クライアントクォータを超えた場合はサーバーエラーです。この場合は5xxを避けてください。