最初の本格的なAPIを構築しています。ユーザーがPOSTデータをどのようにすべきかを決定しようとしています。
POST変数を許可します。これはHTMLフォームが行うことです。
param1=foo¶m2=bar
または、それらにPOST JSONを許可することもできます。これは、ユーザーにJSON応答を返すため、これも理にかなっています。
{"param1":"&","param2":"bar"}
これらのうちどれを使用すべきかについての正式な基準はありますか?これらのアプローチのどちらかに賛成または反対する強力な議論はありますか?
JSONは(はるかに)2つの中で最も柔軟でモダンなオプションなので、私はそれを採用します。特に、JSONで応答を返すことにすでに決めている場合。
とはいえ、APIの利用者にとって有益である場合、両方をサポートできない理由はありません。 HTMLフォームは、Content-Type
HTTPヘッダーがapplication/x-www-form-urlencoded
に設定されるHTTPリクエストでコンテンツを送信しますが、JSONの正しいコンテンツタイプはapplication/json
です。
一部のフレームワーク。 ASP.NET Web API 受信リクエストの自動シリアル化を提供します(XMLかJSONかに関係なく、このフレームワークがフォームのエンコーディングをサポートしているかどうかを確認し、このタスクの負担をあなたから解放します。
REST APIを作成している場合、 Swagger 仕様を使用できます。これは、簡単に開発および消費するためのインターフェースを作成するRESTful APIを記述する定義形式(YAML)ですリソースとそれに関連付けられた操作をマッピングすることによりAPIを提供します。言語に依存しないため、多くのサーバー/クライアント側の言語のサービスを生成でき、読み取り可能で、何よりもAPI仕様のドキュメントが生成されます。
彼らにjsonをポストさせることで、受け取るデータ構造をより用途が広く、正確にすることができます。ただし、POST変数を使用すると、WebブラウザーでAPIを簡単に使用できます。
リクエストが常にサーバー間であることがわかっている場合、または非常に複雑な入力がある場合は、jsonを使用します。入力が非常に単純な場合、POST vars。を使用すると、APIがより簡単になります。
または、それらにPOST JSONを許可することもできます。これは、ユーザーにJSON応答を返すため、これも理にかなっています。
まあ、応答形式は、要求形式を制約または条件付けすべきではありません。
ポステルの法則、ロバストネスの原理とも呼ばれます に興味があるかもしれません。
リクエストとレスポンスの両方で異なる表現形式をサポートするとよいでしょう。堅牢性の鍵は、形式(json、xml、csv)ではなく、リソース(モデルまたはデータ構造)の厳密な表現にあります。
それで、質問に関して。両方をサポートすることをお勧めします(クエリ文字列とリクエスト本文)。
APIのセキュリティに関する考慮事項。機密データ(パスワード、トークン、個人データ)を伝達することを目的としたエンドポイントの場合、クエリ文字列を介してデータを投稿しないことをお勧めします。代わりに、JSONアプローチまたはhttpヘッダーを使用してください。
Jsonオブジェクトをポストすると、特にパラメーターの1つとしてDateTimeを使用する場合に、より柔軟になります。パラメータが非常に重い場合、クエリ文字列の長さも制限されます。
ただし、単純なPostリクエストの場合、両方のオプションを指定できます。これはAsp.Netの追加のメソッドです。