web-dev-qa-db-ja.com

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

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

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

（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コマースシナリオを考えてみてください。

restpatterns-and-practicesweb-api
11
Jose Alonso Monge

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

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

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

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

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

1）厳密に言えば、GETリクエストでボディを使用できますが、これは一般的ではなく、一般的には推奨されません。たとえば、 HTTP GET with request body 。

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

10
sleske

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サーバーがクエリ文字列全体を記録します。多くの場合、パラメーターデータがプレーンテキストのログに記録されることを望まない場合があります。

  • 本文で取得：これは完璧な答えのようです。ニースデータ構造を許可しながらREST純粋主義者を満足させますが、異常で眉をひそめていますPOST =は本文を送信する標準的な方法です。

2
Ewan