APIからのJSON応答を構造化するための標準またはベストプラクティスはありますか？明らかに、すべてのアプリケーションのデータは異なるため、私が気にすることはあまりありませんが、必要に応じて「応答の定型文」に関心があります。私の意味の例：

成功したリクエスト：

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

失敗したリクエスト：

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

はい、いくつかの標準があります（標準の定義には多少の自由があります）。

1. JSON API -JSON APIは、応答だけでなく、リソースの作成と更新もカバーします。
2. JSend-シンプルで、おそらくあなたはすでに何をしているか。
3. OData JSONプロトコル -非常に複雑です。
4. HAL -ODataに似ていますが、HATEOASのようなものを目指しています。

JSON API記述フォーマットもあります：

• Swagger
  • JSONスキーマ（swaggerで使用されますが、スタンドアロンで使用することもできます）
• JSONでのWADL
• ラム
• HATEOASは理論的には自己記述型であるため、HAL です。

Google JSONガイド

成功応答の戻り data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

エラー応答の戻り error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

クライアントがJSの場合は、を使用if ("error" in response) {}してエラーの有無を確認できます。

私は事実上の標準が実際に浮上していなかったと思います（そして、決してないかもしれません）。しかし、とにかく、ここに私の見解があります：

成功したリクエスト：

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

失敗したリクエスト：

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

利点：成功とエラーの両方で同じトップレベルの要素

欠点：エラーコードはありませんが、必要に応じてステータスを（成功または失敗）コードに変更するか、「コード」という名前の別の最上位アイテムを追加できます。

質問がREST Webサービスの設計に関するものであり、より正確には成功/エラーに関するものであるとします。

デザインは3種類あると思います。

1. HTTPステータスコードのみを使用してエラーが発生したかどうかを示し、標準のエラーに制限します（通常はそれで十分です）。

   • 長所：APIに依存しない標準です。
   • 短所：実際に起こったことに関する情報が少ない。

2. 使用する HTTPステータス+ json本文をます（エラーであっても）。エラー（コード、メッセージ、理由、タイプなど）の統一された構造を定義し、それをエラーに使用します。成功した場合は、予想されるjson応答を返します。

   • 長所：既存のHTTPステータスコードを使用し、エラーを説明するjsonを返すため、標準のままです（何が起こったかについての詳細情報を提供します）。
   • 短所：出力jsonは、エラーか成功かによって異なります。

3. httpステータス（例：常にステータス200）を忘れて、常にjsonを使用し、応答のルートにブール値のresponseValidとエラーオブジェクト（コード、メッセージなど）を追加します。 （成功）が読み込まれます。

   • 長所：クライアントはjson文字列である応答の本文のみを処理し、status（？）を無視します。

   • 短所：あまり標準的ではありません。

選択するのはあなた次第です:)

APIに応じて、2または3を選択します（json REST APIには2を好みます）。REST Apiの設計で経験したもう1つのことは、各リソース（URL）のドキュメントの重要性です。パラメーター、本体、応答、ヘッダーなど+例です。

私はまた、（JAX-RS実装）+ジャージを使用するためにあなたをお勧めしますgenson（javaの/ JSONデータバインディングライブラリ）。genson + jerseyをクラスパスにドロップするだけで、jsonが自動的にサポートされます。

編集：

• ソリューション2は実装が最も困難ですが、ビジネスエラーだけでなく例外も適切に処理できるという利点があり、初期の努力がより重要ですが、長期的には勝ちます。

• ソリューション3はサーバー側とクライアントの両方で簡単に実装できますが、responseValid +エラーを含む応答オブジェクトに返すオブジェクトをカプセル化する必要があるため、あまり良くありません。

RFC 7807：問題の詳細HTTP APIのは、現時点では公式の標準に我々が持っている最も近いものです。

以下は、Instagramが使用しているjson形式です

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

私はこれが標準であると主張するほど傲慢ではないので、「私が好む」形式を使用します。

私は簡潔な応答を好みます（/ articlesのリストを要求するとき、記事のJSON配列が必要です）。

私のデザインでは、ステータスレポートにHTTPを使用しています。200はペイロードのみを返します。

400はリクエストの何が問題かを示すメッセージを返します。

{"message" : "Missing parameter: 'param'"}

リターン404モデル/コントローラー/ URIが存在しない場合はます

私の側での処理でエラーが発生した場合、次のメッセージで501を返します。

{"message" : "Could not connect to data store."}

私が見てきたことから、かなりの数のREST風のフレームワークがこれらの線に沿っている傾向があります。

根拠：

JSONはペイロード形式であることが想定されており、セッションプロトコルではありません。詳細なセッション風のペイロードの全体的なアイデアは、XML / SOAPの世界と、これらの肥大化した設計を作成したさまざまな誤った選択から来ています。すべてが大きな頭痛の種であることを認識した後、REST / JSONのすべてのポイントは、KISSを使用してHTTPを遵守することでした。私はどちらのJSendにもリモートで標準があるものはないと思います。特に、それらの間でより冗長なものはありません。XHRはHTTP応答に反応します。AJAXにjQueryを使用する場合（ほとんどの場合と同様）、try/ catchおよびdone()/ fail()コールバックを使用してエラーをキャプチャできます。JSONでステータスレポートをカプセル化することがそれ以上に便利であることがわかりません。

価値があることについては、これを別の方法で行います。呼び出しが成功すると、JSONオブジェクトのみが含まれます。trueを示す成功フィールドと、JSONオブジェクトを含むペイロードフィールドを含む、より高いレベルのJSONオブジェクトは必要ありません。ヘッダーのHTTPステータスに対して、200または200の範囲で適切なものを含む適切なJSONオブジェクトを返すだけです。

ただし、エラー（400ファミリーの何か）がある場合は、整形式のJSONエラーオブジェクトを返します。たとえば、クライアントがメールアドレスと電話番号を使用してユーザーをPOSTし、これらの1つが不正な形式である（つまり、基になるデータベースに挿入できない）場合、次のような結果を返します。

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

ここで重要なのは、「フィールド」プロパティは、検証できなかったJSONフィールドと正確に一致する必要があるということです。これにより、クライアントはリクエストの何が問題であったかを正確に知ることができます。また、「メッセージ」はリクエストのロケールにあります。「emailAddress」と「phoneNumber」の両方が無効な場合、「errors」配列には両方のエントリが含まれます。409（競合）JSON応答本文は次のようになります。

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

HTTPステータスコードとこのJSONを使用すると、クライアントは決定論的な方法でエラーに応答するために必要なすべてを備え、HTTPステータスコードを完全に置き換えようとする新しいエラー標準を作成しません。これらは400エラーの範囲でのみ発生することに注意してください。200の範囲にあるものについては、適切なものを返すだけです。私にとっては、HALのようなJSONオブジェクトであることがよくありますが、ここでは特に問題になりません。

追加について考えたのは、 "errors"配列のエントリまたはJSONオブジェクト自体のルートにある数値エラーコードです。しかし、今のところ必要はありません。

大きなソフトウェアジャイアント（Google、Facebook、Twitter、Amazonなど）の残りのAPI応答形式については合意していませんが、上記の回答には多くのリンクが提供されており、一部の人々は応答形式を標準化しようとしました。

APIのニーズは異なる可能性があるため、全員を参加させて特定の形式に同意することは非常に困難です。何百万人ものユーザーがAPIを使用している場合、なぜ応答形式を変更するのですか？

以下は、Google、Twitter、Amazon、およびインターネット上のいくつかの投稿に触発された応答形式に対する私の見解です。

https://github.com/adnan-kamili/rest-api-response-format

Swaggerファイル：

https://github.com/adnan-kamili/swagger-sample-template

JSONのポイントは、JSONが完全に動的で柔軟であることです。これは、1つのノードをルートとするシリアル化されたJavaScriptオブジェクトと配列のセットにすぎないので、好きなように曲げてください。

ルートノードのタイプはあなた次第であり、ルートノードに含まれるものはあなた次第です。応答とともにメタデータを送信するかどうかは、mime-typeを設定するか、application/jsonそのままにするかtext/plainはあなた次第です（エッジケースの処理方法を知っている限り）。

好きな軽量スキーマを作成します。
個人的に、オンラインゲーミング用のアナリティクストラッキングとmp3 / ogg配信、イメージギャラリー配信、テキストメッセージングとネットワークパケット、ブログ投稿とブログコメントはすべて、何が何であるかに関して非常に異なる要件を持っていることがわかりました送信され、何が受信され、どのように消費されるべきか。

それで、私が望む最後のことは、それをすべて行うときに、それぞれをXML2.0などに基づく同じボイラープレート標準に準拠させることです。

そうは言っても、あなたにとって意味のある、よく考えられたスキーマを使用することについては多くのことが言われています。
いくつかのAPI応答を読んで、好きなものを書き留め、好きでないものを批判し、それらの批判を書き留め、なぜ彼らが間違った方法でこすったのかを理解し、そしてあなたが学んだことをあなたが必要なものに適用する方法について考えてください。

JSON-RPC 2.0は標準のリクエストとレスポンスのフォーマットを定義しており、REST APIを使用した後の新鮮な空気です。

後で来る人のために、HAL、JSend、JSON APIを含む承認された回答に加えて、調べる価値のある他のいくつかの仕様を追加します。

• JSON-LDは、W3C勧告であり、JSONで相互運用可能なWebサービスを構築する方法を指定します
• RESTのIon Hypermedia Type。「RESTのシンプルで直感的なJSONベースのハイパーメディアタイプ」と自称しています。

提案された基本的なフレームワークは問題ないように見えますが、定義されているエラーオブジェクトは非常に制限されています。多くの場合、問題を表すために単一の値を使用することはできず、代わりに一連の問題と原因が必要になります。

少し調べてみたところ、エラー（例外）を返す最も一般的な形式は次の形式の構造であることがわかりました。

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

これは、OASISデータ標準OASIS ODataによって提案された形式であり、最も標準的なオプションのようですが、現時点では、どの標準の採用率も高くないようです。この形式は、JSON-RPC仕様に準拠しています。

これを実装する完全なオープンソースライブラリは、 Mendocino JSON Utilitiesにあります。このライブラリは、JSONオブジェクトと例外をサポートしています。

詳細は、JSON REST APIでのエラー処理に関する私のブログ投稿で説明されています。

常識以外に、法律違反や無法基準はありません。2人が話しているようにこれを抽象化する場合、標準は、最小の時間で最小の言葉でお互いを正確に理解できる最良の方法です。私たちの場合、「最小の単語」はトランスポート効率のために帯域幅を最適化し、「正確に理解する」はパーサー効率のための構造です。最終的にはデータが少なくなり、一般的な構造になります。ピンホールを通過し、共通のスコープで（少なくとも最初は）解析できるようにします。

提案されているほとんどすべてのケースで、私は「成功」と「エラー」のシナリオに対して別々の応答を目にしています。これら2つのケースで応答が異なる場合、なぜ本当に「成功」​​フラグをそこに置く必要があるのですか？「エラー」の欠如が「成功」であることは明らかではありませんか？「エラー」が設定された「成功」がTRUEである応答を持つことは可能ですか？または、「エラー」が設定されていない「成功」はFALSEですか？1つのフラグだけでは不十分ですか？「エラー」フラグは「成功」よりも「エラー」の方が少ないと思うので、「エラー」フラグのみを使用したいと思います。

また、本当に「エラー」をフラグにする必要がありますか？複数の検証エラーで応答したい場合はどうなりますか？したがって、各エラーをそのノードの子として持つ「エラー」ノードを作成する方が効率的です。空の（ゼロまで数える）「エラー」ノードは「成功」を示します。

モバイル開発者が簡単に理解できるWeb APIのベストレスポンス。

これは「成功」応答用です

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

これは「エラー」応答用です

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}