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!"
}
}
はい、出現したいくつかの標準があります（標準の定義にはいくつかの自由がありますが）：
JSON API 記述形式もあります。
質問がREST Webサービスの設計に関するものであり、より正確には成功/エラーに関するものであると仮定します。
3種類のデザインがあると思います。
エラーがあったかどうかを示すためにHTTP ステータス コードのみを使用し、標準のものに制限するようにしてください (通常はそれで十分です)。
HTTP Status + json bodyを使用します(エラーであっても)。エラーの統一構造 (例: コード、メッセージ、理由、タイプなど) を定義し、それをエラーに使用します。成功した場合は、期待される json 応答を返すだけです。
http ステータス(例: 常にステータス 200) を忘れて、常に json を使用し、レスポンスのルートにブール値の responseValid とエラー オブジェクト (コード、メッセージなど) を追加します。 (成功) が入力されます。
長所: クライアントは、json 文字列である応答の本文のみを処理し、ステータス (?) を無視します。
短所：標準的ではありません。
選択するのはあなた次第です:)
API に応じて、2 つまたは 3 つを選択します (json の残りの API には 2 つを好みます)。REST Api の設計で私が経験したもう 1 つのことは、各リソース (url) のドキュメントの重要性です: パラメータ、本文、応答、ヘッダーなど + 例。
また、jersey (jax-rs 実装) + genson (java/json データバインディング ライブラリ) を使用することをお勧めします。クラスパスに genson + jersey をドロップするだけで、json が自動的にサポートされます。
編集：
解決策 2 は実装が最も困難ですが、利点は、ビジネス エラーだけでなく、例外を適切に処理できることです。最初の努力はより重要ですが、長期的には成功します。
解決策 3 は、サーバー側とクライアントの両方で簡単に実装できますが、responseValid + エラーを含む応答オブジェクトで返したいオブジェクトをカプセル化する必要があるため、あまり良くありません。
RFC 7807: HTTP API の問題の詳細は、現時点で公式の標準に最も近いものです。
これが標準であると主張するほど傲慢ではないので、「私が好む」形式を使用します。
私は簡潔な応答を好みます (/articles のリストを要求する場合、記事の JSON 配列が必要です)。
私の設計では、ステータス レポートに HTTP を使用しています。200はペイロードだけを返します。
400は、リクエストの何が問題だったかを示すメッセージを返します。
{"message" : "Missing parameter: 'param'"}
モデル/コントローラー/URI が存在しない場合は404を返します
私の側の処理でエラーが発生した場合は、次のメッセージとともに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 にカプセル化することが、これ以上に役立つとは思えません。
Google、Facebook、Twitter、Amazon などの大手ソフトウェア企業の API 応答形式については合意していませんが、上記の回答には多くのリンクが示されています。
API のニーズは異なる可能性があるため、全員を参加させて何らかの形式に同意させることは非常に困難です。何百万人ものユーザーが API を使用している場合、なぜ応答形式を変更するのでしょうか?
以下は、Google、Twitter、Amazon、およびインターネット上のいくつかの投稿に触発された応答形式に関する私の見解です。
https://github.com/adnan-kamili/rest-api-response-format
Swagger ファイル:
JSON のポイントは、完全に動的で柔軟であることです。これは単一のノードをルートとするシリアル化された JavaScript オブジェクトと配列のセットにすぎないため、気まぐれに好きなように曲げてください。
ルートノードのタイプはあなた次第です。それに含まれるものはあなた次第です。応答とともにメタデータを送信するかどうかはあなた次第です。MIME タイプを設定するapplication/jsonかそのままにしておくかtext/plainはあなた次第です (エッジケースの処理方法を知っている限り）。
好きな軽量スキーマを構築します。
個人的には、分析追跡と mp3/ogg の提供、画像ギャラリーの提供、テキスト メッセージとオンライン ゲームのネットワーク パケット、ブログの投稿とブログのコメントはすべて、何が重要かという点で非常に異なる要件を持っていることがわかりました。送信され、何が受信され、どのように消費されるべきか。
そのため、これらすべてを実行する際に、XML2.0 などに基づく同じボイラープレート標準にそれぞれを準拠させようとすることは、私が最も避けたいことです。
とはいえ、自分にとって意味があり、よく考えられたスキーマを使用することについては、多くのことが言えます。
API の応答をいくつか読んで、気に入った点をメモし、気に入らなかった点を批判し、それらの批判を書き留めて、なぜそれが間違った方向に進むのかを理解してから、学んだことを必要なものに適用する方法を考えてください。
JSON-RPC 2.0は、標準の要求と応答の形式を定義し、REST API を使用した後の新鮮な空気です。
少し遅れましたが、これが HTTP エラー応答に対する私の見解です。コード (ステータスを介して)、一般的なメッセージ、および詳細 (特定のエンドポイントの詳細を提供したい場合、いくつかは自明であるため、詳細は必要ありません) を送信します。ただし、ユース ケースによっては、カスタム メッセージまたは完全なスタック トレースの場合もあります）。成功するためには、同様の形式、コード、メッセージ、および data プロパティ内のデータです。
ExpressJS 応答の例:
// Error
res
.status(422)
.json({
error: {
message: 'missing parameters',
details: `missing ${missingParam}`,
}
});
// or
res
.status(422)
.json({
error: {
message: 'missing parameters',
details: 'expected: {prop1, prop2, prop3',
}
});
// Success
res
.status(200)
.json({
message: 'password updated',
data: {member: { username }}, // [] ...
});