web-dev-qa-db-fra.com

Meilleure pratique pour REST appel API avec de nombreux paramètres

J'ai une API REST avec des opérations GET qui reçoivent une (longue) liste de paramètres (8 paramètres par exemple). Le but de cette opération est de rechercher et filtrer des éléments.

Quelle est la meilleure pratique pour gérer ce scénario?:

(1) Recevoir une liste de paramètres ?:

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

(2) Ou recevez un objet qui encapsule ces paramètres ?:

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

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

Pensez à un scénario de commerce électronique dans lequel vous souhaitez rechercher et filtrer des "produits" par nom, description, catégorie, marque, modèle, prix, etc ...

restpatterns-and-practicesweb-api
11
Jose Alonso Monge

J'ai une API REST avec des opérations GET qui reçoit une (longue) liste de> paramètres. Quelle est la meilleure pratique pour gérer ce scénario?

AFAIK, il n'y a pas de bonne pratique bien établie (désolé). Cependant, on peut faire quelques recommandations:

  • Essayez de éviter d'utiliser POST (au lieu de GET) si la demande est sûr (c'est-à-dire sans effet secondaire, en particulier sans modification des données). Si les paramètres sont très grands, vous devrez peut-être utiliser POST pour contourner les limitations de longueur, mais ce n'est généralement pas un problème (la plupart des logiciels prennent en charge des URL assez longues), et les requêtes sécurisées doivent utiliser GET pour permettre des optimisations telles que la mise en cache et la prélecture.

  • Si vous utilisez GET, vous devez envoyer vos paramètres en tant que paramètres d'URL1). Dans cette situation, la solution naturelle et courante consiste à utiliser une liste de paramètres , c'est donc ce que je recommanderais. Oui, la liste sera longue, mais l'API REST est (probablement) destinée à un usage programmatique, donc je ne vois aucun problème avec cela. Les utilisateurs de l'API sont libres d'encapsuler le paramètres dans un objet à l'intérieur de leur propre code.

  • Techniquement, vous pouvez également mettre un objet dans un paramètre d'URL (comme JSON, XML ou autre), mais cela est inhabituel, donc je l'éviterais si possible.

1) À strictement parler, vous pouvez utiliser un corps avec une requête GET, mais cela est inhabituel et généralement déconseillé; voir par exemple HTTP GET avec corps de requête .

Enfin, tout comme pour les méthodes dans le code source qui ont de longues listes de paramètres, vous voudrez peut-être déterminer si l'API REST a besoin d'une refactorisation. Tout comme dans le code source, une longue liste de paramètres indique la Le point de terminaison de l'API fait beaucoup de choses différentes. Est-il judicieux de le diviser ou de fournir des paramètres par défaut? Mais c'est une question différente ...

10
sleske

La meilleure pratique consiste à POST les paramètres en tant qu'objet.

Cela évite la limite de longueur d'URL et d'autres problèmes avec les chaînes de requête. Si vous envoyez plusieurs paramètres en JSON, un objet est la manière standard de le faire, donc la désérialisation en un est logique.

Vous pouvez éviter de créer des objets de "demande" aléatoires qui ne sont utilisés que dans vos contrôleurs en désérialisant en un objet dynamique si vous le souhaitez; bien que la conversion vers les bons types par la suite puisse être tout aussi compliquée.

Autrefois, vous auriez pu avoir plusieurs paramètres dans votre action de contrôleur automatiquement liés aux champs d'un objet JSON entrant. Mais cela ne fonctionne plus dès le départ dans le noyau .net.

Bien qu'il y ait ceci, que je pourrais être tenté d'essayer

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

Edit: Je vais juste ajouter quelques points sur l'utilisation de GET

  • Mise en cache: GET sera mis en cache par les clients qui obéissent à la spécification HTTP. Mais la spécification est conçue pour accélérer le chargement des pages Web. La mise en cache est utile si le résultat de votre API a les mêmes exigences de cache qu'une page Web, mais inutile si ce n'est pas le cas. Vous pouvez ajouter votre propre mise en cache des réponses POST dans le client si nécessaire).

  • Longueur de l'URL: c'est principalement un problème lorsque vous envoyez un tableau. Évidemment, un tableau peut facilement devenir très long et les noms des paramètres de la chaîne de requête seront répétés pour chaque élément. Cependant, même si vous n'envoyez qu'une chaîne, techniquement cette chaîne peut être très très longue.

  • Journalisation: Par défaut, de nombreux serveurs Web enregistrent la chaîne de requête entière. Souvent, vous ne voulez pas que les données de paramètres se retrouvent dans des journaux en texte brut.

  • GET with body: Cela semblerait être la réponse parfaite, satisfaisant REST purists tout en permettant une structure de données Nice, mais il est inhabituel et désapprouvé, un POST = est le moyen standard d'envoyer un corps.

2
Ewan