REST APIエラーコード構造体を返します

Question

私はREST APIを作成していますが、問題が発生しました。検証エラーを返す最善の方法は何ですか。

私は一般的なエラーコードにダンプエラーメッセージを返すていた今まで

{ 
    "status": 400, 
    "error": { 
     "code": 1, // General bad request code 
     "message": [ 
       "The Key \"a\" is missing", 
       "The Key \"b\" is missing", 
       "The Key \"c\" is missing", 
       "Incorrect Format for field \"y\"" 
     ] 
    } 

) 

私は良いAPIの応答は次のようになりますべきかについて、もう少し研究している（のは、例えば不正な要求をしましょう）そして私は、次のオプションを考えた：最初に発生したエラーで

1. 停止し、特定のエラーコード

   で応答を返します

2. すべての要求データを解析し、複数のフィールド検証エラーを返します。私の意見オプション2では

   { 
       "status": 400, 
       "error": { 
       "code": 1 //General bad Request code 
       "message": "Bad Request", 
       "developer_message": "Field validation errors." 
       "more_info": "www.api.com/help/errors/1", 
       "error_details": { 
         0: { 
           "code": 2 // Specific field validation error code 
           "message": "Field \"x\" is missing from the array structure", 
           "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
           "more_info": "www.api.com/help/errors/2" 
          }, 
   
         1: { 
           "code": 3 // Specific field validation error code 
           "message": "Incorrect Format for field \"y\"", 
           "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
           "more_info": "www.api.com/help/errors/3" 
          } 
           } 
        } 
       } 
   

正しい方法でしょう（それは、開発者/エンドユーザーに有用な情報を提供し、サーバーの負荷が低くなる可能性がある有効なデータを再検証する（より少ない要求/不要/署名を計算してユーザーを認証する必要はありません））、ベストプラクティスとは何か、そしてこの種の問題を処理する別の方法があるかどうかを迷いつつあります。

また私は、スクリプトの流れの中で、単一の致命的なエラーが出る場合は、オプション1がまだ有効であると考えています。（ない検証エラー）

ことが容易であるだけので、コードは単純な配列であることに注意してくださいに従う。応答形式はJSONまたはXMLです。

Answer 1

個人的に私はユーザーに詳細を知らせずに、データベースログテーブルまたはシステムログの開発者に必要なエラーをダンプします。実際にあなたはJSONを使用しています。これはApacheサーバーで最も一般的です。コードはPHPと思われます（ただし中括弧を使用したコード例はPASCALなどのC言語、C＃PERL、PHP、 Cシャープ）。ここでは、PHPの方法がわからない場合は、出力カスタムエラーをシステムログに出力する方法を示します。http://php.net/manual/en/function.syslog.phpあなたがJSONとCSharpでレアな設定のIISを使用している場合も、同様のことを行う.NETライブラリがあります。エラーが発生したときにユーザーにあまりにも多くの情報を与えると、将来的にハッカーにあなたのウェブサイトを調査する方法を与えることになります。

Answer 2

私は2回自分で2回使用しました。 ＃1よりも優れていますか？私はそれがあなたのAPIがどのように使われているかにかかっていると思います。

私は＃2が好きです。これは、いくつかのテストコールでAPIをテストしている開発者に、リクエストで行ったすべてのエラー/ミスの概要を簡単に示しているためです。その要求を有効にする。エラーを1つ1つ返す場合（＃1のように）、今度は有効であることを期待して、リクエストを再試行し続けてください。

しかし、＃2は開発者にとって非常に便利だと言われていますが、理由は実際にはエンドユーザーには当てはまりません。エンドユーザーは、通常どのように実装されているか気にしません。ソフトウェアが5つのエラーを返す1つの要求を行っているか、それとも1つのエラーをそれぞれ返す5つの後続の要求を行っているか。
クライアントでうまく処理されている限り、エンドユーザーは違いに気づくべきではありません。その処理方法は、クライアントが実際にがであるかどうかによって大きく異なります。

開発のスピードアップに次いで、＃2のもう1つの利点は、要求が少なくてすみますが、サーバー負荷が軽減されることです。

---

I would like to know if anyone went #2 and maybe have any improvements on it so I opened a bounty.

確かになされるべき改良点があります。そのままでは、体内には省略可能なデータがあります。

{ 
    "status": 400, 
    "error": { 
    "code": 1 //General bad Request code 
    "message": "Bad Request", 
    "developer_message": "Field validation errors." 
    "more_info": "www.api.com/help/errors/1", 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

HTTP応答では、ステータスコードは本文には挿入されず、ヘッダーに挿入されます。つまり、ここで"status": 400と"message": "Bad Request"を省略することができます。 400は応答のステータスコードであり、400は不正リクエストを意味します。これはHTTP標準であり、レスポンスで説明する必要はありません。また、"developer_message": "Field validation errors."は重複しています。具体的なエラーはそれぞれ別のエラーに既に含まれているためです。

{ 
    "error": { 
    "code": 1 //General bad Request code 
    "more_info": "www.api.com/help/errors/1", 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

---

"code": 1 //General bad Request code 
"more_info": "www.api.com/help/errors/1", 

は、これらの2行は、本当に今はもう意味がありません残し

。 「は、それぞれのエラーは、それが自身のコードと情報のリンクのしているので、彼らはまた、必要とされていないので、我々はこの

{ 
    "error": { 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

400のステータスコードがすでに誤りがあったことを示したまま、同様にこれらの行を取り除くかもしれませんので、あなたはドン"error": {error details}をもう一度示す必要があります。エラーが発生していることがわかっているためです。エラーのリストは、単純にルートオブジェクトになることができます。

[ 
    { 
     "code": 2//Specificfieldvalidationerrorcode 
     "message": "Field \"x\" is missing from the array structure", 
     "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
     "more_info": "www.api.com/help/errors/2" 
    }, 
    { 
     "code": 3//Specificfieldvalidationerrorcode 
     "message": "Incorrect Format for field \"y\"", 
     "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
     "more_info": "www.api.com/help/errors/3" 
    } 
] 

したがって、本文に残っているのは単にエラーの一覧です。

ステータスコードは応答ヘッダーで指定されています。
詳細は応答本文で指定されています。

Answer 3

まずは、お客様のレストAPIメソッドのドキュメントを提供していたはずです。したがって、顧客/開発者からパラメータの有効なデータを提供することが期待されます。

今や、＃1がRest APIを実行する最善の方法だと言っています。開発者の責任は、サーバーの使用を可能な限り減らすことです。したがって、致命的なエラーが発生した場合は、対応するエラーコードとエラーメッセージを含むレスポンスを作成して返します。

また、遭遇した後にさらにエラーが発生することは確かではありません。そのため、残りのデータを解析する必要はありません。最悪の場合を考えればうまく動作しません。

Answer 4

Facebook's Graph APIを見てみましょう。それは激しく打撃を受け、非常に多くのエラーが発生する可能性が最も高いです。ここではFacebookはAPIエラーに返すものです：

{ 
    "error": { 
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190, 
    "error_subcode": 460, 
    "error_user_title": "A title", 
    "error_user_msg": "A message" 
    } 
} 

彼らはできるだけグラフAPIをとして有用であるようにしよう、しかし、彼らは、コードとサブコード（Ref）で特定のエラーを返すように見えます。各エラーに独自のコードがあるということは、デバッグの開始点として前記コードまたはメッセージを検索する方が簡単であることを意味します。これはおそらく、彼らが公式のエラー応答にエラーメッセージを蓄積しない理由です。それが十分にFacebookのために便利であれば、それはおそらく私たちのために十分です。

サンプルエラー応答：

{ 
    "error": { 
    "message": "(#200) Must have a valid access_token to access this endpoint", 
    "type": "OAuthException", 
    "code": 200 
    } 
} 

と

"error": { 
    "message": "(#604) Your statement is not indexable. The WHERE clause must contain 
    an indexable column. Such columns are marked with * in the tables linked from 
    http://developers.facebook.com/docs/reference/fql ", 
    "type": "OAuthException", 
    "code": 604 
} 

---

そして、ウェブサーバーからどのようにJSONレスポンスのためのいくつかのルールを定めて仕様がある」JSendがあるはずフォーマットされている。彼らの目標は次のとおりです。ここで

There are lots of web services out there providing JSON data, and each has its own way of formatting responses. Also, developers writing for JavaScript front-ends continually re-invent the wheel on communicating data from their servers. While there are many common patterns for structuring this data, there is no consistency in things like naming or types of responses. Also, this helps promote happiness and unity between backend developers and frontend designers, as everyone can come to expect a common approach to interacting with one another.

は、サンプルエラーメッセージです：

{ 
    "status" : "fail", 
    "data" : { "title" : "A title is required" } 
} 

それはFacebookのように見え、業界標準のように設定しようと、このグループはあなたの選択の＃1を選ぶされています。

---

バウンティ質問

の恵みの要求に応じて、「誰もが＃2を行って、多分それ上の任意の改善を持っている場合はどうなりますか？」、と述べPragmatic RESTful APIからデザインパターンがあります：

Validation errors will need a field breakdown. This is best modeled by using a fixed top-level error code for validation failures and providing the detailed errors in an additional errors field, like so:

は、

{ 
    "code" : 1024, 
    "message" : "Validation Failed", 
    "errors" : [ 
    { 
     "code" : 5432, 
     "field" : "first_name", 
     "message" : "First name cannot have fancy characters" 
    }, 
    { 
     "code" : 5622, 
     "field" : "password", 
     "message" : "Password cannot be blank" 
    } 
    ] 
} 

Answer 5

私は最近、結果に複数の警告またはエラーを返すRest APIに対して取り組みました。次のようにサンプル＃2から始めて、私はそれを修正します：

{ 
    "status": 400, 
    "results" : null, 
    "warnings": { 
     0: { 
       // Build a warning message here, sample text to show concept 
       "code": 1 // Specific field validation error code 
       "message": "It is no longer neccessary to put .js on the URL" 
      } 
    } 
    "errors": { 
     0: { 
       "code": 2 // Specific field validation error code 
       "message": "Field \"x\" is missing from the array structure" 
       "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
      }, 
     1: { 
       "code": 3 // Specific field validation error code 
       "message": "Incorrect Format for field \"y\"", 
       "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"" 
      } 
     } 
    } 

これはあなたの応答に、必要に応じて複数の警告やエラーが発生して、結果を提供する能力を提供します。

はい、これは構造に膨らみがありますが、開発者がいつも同じ構造でデータを取り戻すための簡単なインターフェイスを提供します。

私もの代わりに、すべてのエラーに彼らは（エラーコードを使用してヘルプを見つける方法）APIドキュメントである必要があり私見として以下の項目を削除します：私は「、これらの同じ線に沿って

"more_info": "www.api.com/help/errors/2" 
"more_info": "www.api.com/help/errors/3" 

messageとdeveloper_messageの両方が必要かどうかわかりません。呼び出し元がデータを正しく提供できなかった場合、APIからユーザーエラーメッセージを提供しようとしているかのように、重複しているようです。

Answer 6

APIは人間用ではありません。したがって、詳細なエラーテキストを返す必要はありません。 「欠落しているパラメータ」を意味するエラーコードを返すことさえできます。それをうまく文書化することを忘れないでください。