Comprendre la liaison de paramètres dans l'API Web ASP.Net

L'API Web ASP.Net est une infrastructure légère qui peut être utilisée pour créer des services HTTP RESTful. Lorsque vous travaillez avec des méthodes de contrôleur dans l'API Web, vous devrez souvent transmettre des paramètres à ces méthodes. Un «paramètre» fait ici simplement référence à l'argument d'une méthode, tandis que la «liaison de paramètres» fait référence au processus de définition des valeurs des paramètres des méthodes de l'API Web.

Notez que l'API Web peut lier des paramètres de deux manières: la liaison de modèle et les formateurs. La liaison de modèle est utilisée pour lire à partir de la chaîne de requête, tandis que les formateurs sont utilisés pour lire à partir du corps de la requête. Vous pouvez également utiliser des convertisseurs de type pour permettre à l'API Web de traiter une classe comme un type simple, puis de lier le paramètre à partir de l'URI. Pour ce faire, vous devez créer un TypeConverter personnalisé. Vous pouvez également créer un classeur de modèle personnalisé en implémentant l'interface IModelBinder dans votre classe, puis en implémentant la méthode BindModel. Pour en savoir plus sur les convertisseurs de types et les classeurs de modèles, consultez cette documentation Microsoft.

Désormais, pour lier des paramètres, l'API Web suit cette règle: pour les types simples, l'API Web essaie d'obtenir la valeur à partir de l'URI, et pour les types complexes, l'API Web tente d'obtenir la valeur du corps de la requête. Les types simples ici font référence aux types primitifs .Net (int, bool, double, float, etc.) et à d'autres types qui incluent TimeSpan, DateTime, Guid, decimal et string. Il inclut également tout type pour lequel un convertisseur de type est disponible et peut convertir à partir d'une chaîne. Dans la section suivante, nous explorerons les attributs [FromBody] et [FromUri] utilisés pour lier respectivement les valeurs du corps de la requête et de l'URI.

Quand utiliser [FromBody] et [FromUri] dans l'API Web

Si vous utilisez l'API Web depuis un certain temps, vous connaissez peut-être les attributs [FromBody] et [FromUri]. L'attribut [FromUri] est préfixé au paramètre pour spécifier que la valeur doit être lue à partir de l'URI de la demande, et l'attribut [FromBody] est utilisé pour spécifier que la valeur doit être lue à partir du corps de la demande.

Pour tous les types primitifs (int, double, float, etc.), le runtime de l'API Web tente de lire la valeur à partir de l'URI de la requête HTTP. Pour les types complexes (instances de classes), le moteur d'exécution de l'API Web tente de lire la valeur à partir du corps de la requête HTTP à l'aide d'un formateur de type média. Il s'agit du comportement par défaut de l'API Web. 

Par conséquent, si vous avez une valeur dans l'URI de demande qui est un type primitif, vous n'avez pas besoin de spécifier l'attribut [FromUri]. De même, si vous avez une valeur dans le corps de la requête qui est un type complexe, vous n'avez pas besoin de spécifier l'attribut [FromBody]. Cependant, si le type primitif réside dans le corps de la requête ou si le type complexe réside dans l'URI de la requête, vous devez spécifier l'attribut [FromBody] ou [FromUri]. La raison est que vous vous écartez du comportement par défaut dans les deux cas.

Comment utiliser [FromBody] et [FromUri] dans l'API Web

L'extrait de code suivant illustre comment vous pouvez spécifier l'attribut [FromBody] pour un type de données fondamental transmis en tant que paramètre à une méthode d'API Web.

classe publique SecurityController: ApiController

{

    Public HttpResponseMessage Post ([FromBody] int id)

    {

       // Écrivez votre code ici

    }

}

Et voici un extrait de code qui illustre comment vous pouvez passer un type complexe en tant que paramètre à une méthode d'API Web à l'aide de l'attribut FromUri.

classe publique SecurityController: ApiController

{

    Public HttpResponseMessage Post (utilisateur [FromUri] User)

    {

       // Écrivez votre code ici

    }

}

Il convient de noter que l'envoi de données d'authentification utilisateur telles que le nom d'utilisateur et le mot de passe via l'URI n'est pas une bonne pratique, même si vous utilisez peut-être SSL. En effet, ces données peuvent être enregistrées dans les journaux du navigateur, où elles sont vulnérables à l'exposition. Lors du passage de données sensibles (noms d'utilisateur, mots de passe, informations de carte de crédit, etc.) via le corps de la requête, il est impératif d'utiliser [FromBody] dans tous les cas.

Notez que lorsque vous utilisez l'attribut [FromBody] lors de la transmission d'un paramètre à une méthode d'API Web, le moteur d'exécution de l'API Web tire parti de l'en-tête de type de contenu pour sélectionner le formateur approprié. Vous pouvez en savoir plus sur la négociation de contenu dans l'API Web dans mon article ici.