asp.net-web-api
Négociation du contenu de l'API Web ASP.NET
Recherche…
Informations de base sur la négociation du contenu de l'API Web ASP.NET
La négociation de contenu peut être définie comme le processus de sélection de la meilleure représentation pour une ressource donnée. Ainsi, la négociation de contenu signifie que le client et le serveur peuvent négocier entre eux afin que le client puisse obtenir des données en fonction de leur format requis.
Internet dépend de trois points,
- La ressource
- Un pointeur vers la ressource (URL)
- Représentation de ressource
Le troisième point est plus important que les deux autres, car tout fonctionne sur la base de la manière dont nous pouvons voir la ressource. Nous pouvons représenter une ressource sous deux formats.
- Format XML (Extensible Markup Language)
- Format JSON (notation d'objet JavaScript)
L'un des standards du service RESTful est que le client doit avoir la possibilité de décider dans quel format il souhaite obtenir la réponse, en JSON ou XML. Une demande envoyée au serveur inclut un en-tête Accept. A l'aide de l'en-tête Accept, le client peut spécifier le format de la réponse.
Par exemple,
Accept: application/xml renvoie le résultat au format XML
Accept: application/json renvoie le résultat au format JSON
Selon la valeur d'en-tête Accept de la demande, le serveur envoie la réponse. Cela s'appelle la négociation de contenu.
Que se passe-t-il derrière la scène lorsque nous demandons des données dans un format spécifique?
Le contrôleur Web API ASP.NET génère les données que vous souhaitez envoyer au client et les transmet au pipeline d'API Web qui recherche ensuite l'en-tête Accept du client. Ensuite, choisissez un formateur approprié pour formater les données.
Comme l'API Web ASP.NET est très extensible, nous pouvons également spécifier plusieurs valeurs pour l'en-tête d'acceptation dans l'en-tête de la demande.
Accept: application/xml,application/json
Dans le cas ci-dessus, le serveur choisit le premier formateur pour formater les données de la réponse.
Nous pouvons également spécifier le facteur de qualité dans l'en-tête accept. Dans ce cas, le serveur choisit un format présentant un facteur de qualité supérieur.
Accept: application/json;q=0.8,application/xml;q=0.5
Si nous ne spécifions aucun en-tête Accept, le serveur choisit par défaut le formateur JSON.
Lorsque la réponse est envoyée au client dans le format demandé, notez que l'en Content-Type tête Content-Type de la réponse est défini sur la valeur appropriée. Par exemple, si le client a demandé l' application/xml , le serveur envoie les données au format XML et définit également Content-Type=application/xml .
Les formateurs sont utilisés par le serveur pour les messages de demande et de réponse. Lorsque le client envoie une demande au serveur, nous définissons l'en-tête Content-Type sur la valeur appropriée pour permettre au serveur de connaître le format des données que nous envoyons.
Par exemple, si le client envoie des données JSON, l'en-tête Content-Type est défini sur application/json . Le serveur sait qu'il traite les données JSON. Il utilise donc le formateur JSON pour convertir les données JSON en .NET Type. De même, lorsqu'une réponse est envoyée du serveur au client, en fonction de la valeur de l'en-tête Accept, le formateur approprié est utilisé pour convertir le type .NET en JSON, XML, etc.
Exemple de différents types de format de réponse:
application / json:
{
"Email": "sample string 1",
"HasRegistered": true,
"LoginProvider": "sample string 3"
}
application / xml:
<UserInfoViewModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/WebApiDemo.Models">
<Email>sample string 1</Email>
<HasRegistered>true</HasRegistered>
<LoginProvider>sample string 3</LoginProvider>
</UserInfoViewModel>
Les applications Web modernes peuvent fournir des données dans divers langages et formats. Ainsi, si nous développons notre API pour couvrir les utilisateurs mondiaux à travers le monde, la négociation de contenu est pertinente.
Négociation de contenu dans l'API Web
Comprendre le concept
Pour comprendre la négociation de contenu dans l'API Web, il est important de comprendre le terme Resource .
Sur le Web, toute information à laquelle nous pouvons accéder peut être appelée HTTP resource . Il y a une quantité énorme de matériel à afficher sur le Web qui a différents types de contenu, tels que des documents HTML, des images, de la vidéo, de l'audio, des fichiers exécutables, des feuilles de calcul, etc. La réponse http pour la demande renvoie la ressource et spécifie également le type de contenu, also known as media type .
Pour accéder à une ressource, le client peut effectuer une requête http en fournissant une ressource spécifique uri et les verbes http. Cependant, en plus de cela, le client peut également spécifier le type d'acceptation, qui est le format du contenu recherché par l'utilisateur. Le type «accept-type» peut être défini dans les en-têtes de requête http comme en-tête “accept” .
Le serveur vérifie alors l'en-tête «accept» des demandes et renvoie la réponse au format spécifié, si disponible. Veuillez noter que le serveur ne peut renvoyer la réponse dans la représentation demandée que si elle est disponible . Si la représentation demandée n'est pas disponible, elle renvoie la ressource par défaut. C'est la raison pour laquelle cela s'appelle la négociation de contenu.
Un exemple pratique
Par exemple, supposons que vous faites une demande à http://example.com/customer/1 pour obtenir les informations du client avec l'ID 1. Si vous ne spécifiez pas l'en-tête «accept» dans la demande, le Le serveur retournera la représentation par défaut de cette ressource.
Supposons que le serveur puisse retourner les informations client dans json and xml both . Il appartient maintenant au client de spécifier le format requis des informations client dans l'en-tête «accept» de la demande. La valeur de l'en-tête “accept” peut être “application/json” pour la représentation json ou “text/xml” pour la représentation XML. Le serveur renverra alors la réponse selon le format demandé.
Si le format demandé est «text / html» qui n'est pas pris en charge par cet hôte (comme dans cet exemple), il simply return the resource in the default format . La réponse http contient un en-tête “content-type” qui indique au client le format de la ressource.
Veuillez noter que même dans le cas où la représentation demandée de la ressource n'est pas disponible, la représentation par défaut de la ressource est toujours renvoyée.
C'est pourquoi on parle de négociation de contenu .
Le client négocie la représentation de la réponse, cependant, s’il n’est pas disponible, il en obtient une par défaut.
Comment configurer dans l'API Web
Dans Web API, la négociation de contenu peut être configurée dans la classe WebAPIConfig tant que
config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new System.Net.Http.Headers.MediaTypeHeaderValue("text/html"));
Vous pouvez également remplacer la négociation de contenu par défaut dans l'API Web en implémentant l'interface IContentNegotiator et sa méthode Negotiate, puis la configurer dans la ligne de canal de demande d'API Web, dans le fichier WebAPI.config, comme suit:
GlobalConfiguration.Configuration.Services.Replace(typeof(IContentNegotiator), new CustomContentNegotiator());
Voici un exemple d'implémentation de la méthode Negotiate.
public class CustomContentNegotiator : DefaultContentNegotiator
{
public override ContentNegotiationResult Negotiate(Type type, HttpRequestMessage request, IEnumerable<MediaTypeFormatter> formatters)
{
var result = new ContentNegotiationResult(new JsonMediaTypeFormatter(), new MediaTypeHeaderValue("application/json"));
return result;
}