多くのパラメーターを使用したREST API呼び出しのベストプラクティス

パラメーターの（長い）リスト（たとえば、8つのパラメーター）を受け取るGET操作を備えたREST APIがあります。この操作の目的は、要素を検索してフィルタリングすることです。

このシナリオを管理するためのベストプラクティスはどれですか。：

（1）パラメータのリストを受け取りますか？：

public ResultType Get(int p1, int p2, string p3...) { ... }

（2）または、これらのパラメーターをカプセル化するオブジェクトを受け取りますか？：

public class MyClass
{
    public int X { get; set; }
    public int Y { get; set; }
    public string Z { get; set; }
}

public ResultType Get(MyClass parameter) { ... }

名前、説明、カテゴリ、ブランド、モデル、価格などで「製品」を検索およびフィルタリングするeコマースシナリオを考えてみてください。

>パラメータの（長い）リストを受け取るGET操作を備えたREST APIがあります。このシナリオを管理するためのベストプラクティスはどれですか。

AFAIK、しっかりと確立されたベストプラクティスはありません（申し訳ありません）。ただし、いくつかの推奨事項があります。

• リクエストが安全な場合（つまり、副作用がなく、特にデータを変更しない場合）は（の代わりに）使用POSTしないようにしてください。パラメータが非常に大きい場合は、長さの制限を回避するために使用する必要がある場合がありますが、通常これは問題ではなく（ほとんどのソフトウェアは非常に長いURLをサポートします）、安全な要求を使用して、キャッシュやプリフェッチなどの最適化を許可する必要があります。GETPOSTGET

• を使用する場合はGET、パラメーターをURLパラメーターとして送信する必要があります^1）。そのような状況では、自然で一般的な解決策は、パラメーターのリストを使用することです。そのため、これをお勧めします。はい、リストは長くなりますが、REST APIは（おそらく）プログラムでの使用を目的としているため、この問題は発生しません。APIのユーザーは、独自のコード内のオブジェクトのパラメーターを自由にカプセル化できます。

• 技術的には、オブジェクトをURLパラメーター（JSON、XMLなど）に入れることもできますが、それは珍しいので、可能であれば避けま​​す。

1）厳密に言えば、GETリクエストでボディを使用できますが、これは一般的ではなく、一般的には推奨されません。たとえば、リクエストボディを伴うHTTP GETを参照してください。

最後に、長いパラメーターリストを持つソースコードのメソッドと同様に、REST APIにリファクタリングが必要かどうかを検討する必要があります。ソースコードと同様に、このような長いパラメーターリストは、APIエンドポイントがさまざまなことを実行していることを示します。それを分割したり、デフォルト設定を提供したりするのは理にかなっていますか？しかし、それは別の質問です...

ベストプラクティスは、パラメーターをオブジェクトとしてPOSTすることです。

これにより、URLの長さの制限やクエリ文字列に関するその他の問題を回避できます。JSONで複数のパラメーターを送信する場合、オブジェクトはそれを行うための標準的な方法であるため、1つにデシリアライズすることは理にかなっています。

必要に応じて動的オブジェクトに逆シリアル化することで、コントローラーでのみ使用されるランダムな「リクエスト」オブジェクトの作成を回避できます。後で正しいタイプにキャストすることも同様に面倒です。

昔は、コントローラーアクションの複数のパラメーターを受信JSONオブジェクトのフィールドに自動的にバインドすることができました。しかし、これは.netコアではそのままでは機能しません。

これがありますが、試してみたくなるかもしれませんが

https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/application-model?view=aspnetcore-2.1#application-model-usage-in-webapicompatshim

編集：GETの使用についていくつかの点を追加するだけです

• キャッシュ：GETは、HTTP仕様に従うクライアントによってキャッシュされます。ただし、この仕様はウェブページの読み込みを高速化するように設計されています。キャッシュは、API結果にWebページと同じキャッシュ要件がある場合に役立ちますが、そうでない場合は役に立ちません。必要に応じて、クライアントに独自のPOST応答のキャッシュを追加できます。

• URLの長さ：これは主に、配列を送信するときの問題です。明らかに、配列は非常に長くなる可能性があり、クエリ文字列パラメーター名はアイテムごとに繰り返されます。ただし、1つの文字列のみを送信する場合でも、技術的にはその文字列は非常に長くなる可能性があります。

• ロギング：デフォルトでは、多くのWebサーバーがクエリ文字列全体を記録します。多くの場合、パラメーターデータがプレーンテキストのログに記録されることを望まない場合があります。

• GET with body：これは完璧な答えのように思われ、REST純粋主義者を満足させながら素敵なデータ構造を可能にしますが、それは珍しく眉をひそめています。POSTは本文を送信する標準的な方法です。