Utiliser un service REST avec HttpClient

5 minutes

Beaucoup de services web modernes implémentent l’architecture REST. Cette structure permet à un service web d’exposer des opérations et des données par le biais d’une série de points de terminaison bien définis. Les requêtes que les applications clientes envoient à un service web REST pour récupérer, modifier, créer ou supprimer des données utilisent un ensemble prédéfini de verbes. Un service web REST répond à ces requêtes de manière standard. Cette approche facilite la construction d’applications clientes.

Le modèle REST est basé sur le protocole HTTP. Une application .NET MAUI peut envoyer des requêtes à un service web REST en utilisant la classe HttpClient. Dans cette leçon, vous allez découvrir HttpClient et comment l’utiliser pour interagir avec un service web REST.

Qu’est-ce que la classe HttpClient ?

HttpClient est une classe .NET qu’une application peut utiliser pour envoyer des requêtes HTTP et recevoir des réponses HTTP d’un service web REST. Un ensemble d’URI identifie les ressources exposées par le service web. Un URI combine l’adresse du service web avec le nom d’une ressource disponible à cette adresse.

La classe HttpClient utilise une API basée sur les tâches pour les niveaux de performance. Elle vous donne accès aux informations contenues dans les messages de requête, telles que les en-têtes HTTP et les codes d’état, ainsi que les corps de message contenant les données envoyées et reçues proprement dites.

Diagramme montrant comment une application cliente utilise un objet HttpClient pour envoyer et recevoir des messages et des réponses HTTP

La classe HttpClient est disponible dans l’espace de noms System.Net.Http. Une application peut créer un objet HttpClient avec le constructeur par défaut :

using System.Net.Http;
...

var client = new HttpClient();

Effectuer des opérations CRUD avec un objet HttpClient

Un service web REST permet à un client d’effectuer des opérations sur des données en utilisant un ensemble de verbes HTTP. Le travail du verbe HTTP est d’indiquer l’action souhaitée qu’il est nécessaire d’effectuer sur une ressource. Il existe de nombreux verbes HTTP, mais les quatre plus courants sont POST, GET, PUT et DELETE. Un service peut implémenter ces verbes pour permettre à une application cliente de gérer le cycle de vie des objets en effectuant des opérations CRUD (Create, Read, Update et Delete), comme suit :

Le verbe POST indique que vous souhaitez créer une ressource.
Le verbe GET indique que vous souhaitez récupérer une ressource.
Le verbe PUT indique que vous souhaitez mettre à jour une ressource.
Le verbe DELETE indique que vous souhaitez supprimer une ressource.

Diagramme montrant les opérations CRUD de base qu’un service REST peut implémenter, notamment obtenir, publier, placer et supprimer.

Créer une ressource avec HttpClient

Pour créer une ressource avec HttpClient, vous pouvez utiliser la méthode SendAsync en lui passant un objet HttpRequestMessage.

L’objet HttpRequestMessage sert à modéliser la requête envoyée au service web. Vous spécifiez le verbe HTTP et l’URL du service web, et vous renseignez la charge utile à envoyer via la propriété HttpRequestMessage.Content.

HttpClient client = new HttpClient();

HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, url);
message.Content = JsonContent.Create<Part>(part);

HttpResponseMessage response = await client.SendAsync(message);

Ce fragment de code effectue les tâches suivantes :

Il crée une instance de HttpClient, appelée client, qu’il utilise pour envoyer un message.
Il crée une instance de HttpRequestMessage, appelée message, qu’il utilise pour modéliser le message. Le message contient le verbe HTTP et l’URL.
Il définit la propriété Content de HttpRequestMessage avec la fonction JsonContent.Create. Cette fonction sérialise automatiquement la variable part en JSON approprié pour l’envoi au service web.
Il envoie le message en utilisant l’objet HttpClient. Un objet HttpResponseMessage est retourné ; il contient des informations telles que le code d’état ainsi que les informations retournées par le service web.

Lire une ressource avec HttpClient

Vous pouvez lire une ressource à partir d’un service web avec la même technique décrite précédemment, sauf que vous devez initialiser HttpRequestMessage avec un HttpMethod.Get. Toutefois, le HttpClient dispose de quelques méthodes pratiques qui sont fournissent des raccourcis.

Pour lire une ressource avec HTTPClient, utilisez la méthode GetStringAsync comme indiqué dans l’exemple suivant :

HttpClient client = new HttpClient();

string text = await client.GetStringAsync("https://...");

La méthode GetStringAsync prend un URI qui référence la ressource et retourne une réponse sous forme de chaîne. La chaîne de réponse est la ressource demandée par l’application. Le format de données de réponse est le format par défaut du service demandé, tel que JSON ou XML. Une application peut inclure l’en-tête MediaTypeWithQualityHeaderValue pour indiquer au service web que les données doivent lui être retournées dans un format particulier. Par exemple, si l’application demande que les données lui soient retournées au format JSON, elle peut utiliser le code suivant :

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

Dans cet exemple, le résultat est retourné sous forme de chaîne et il contient uniquement le corps du message de réponse. Pour obtenir l’intégralité de la réponse, y compris les en-têtes, le corps et le code d’état, appelez la méthode GetAsync. Les données sont retournées sous forme d’objet HttpResponseMessage.

Mettre à jour une ressource avec HttpClient

Pour mettre à jour une ressource en utilisant HttpClient, ajoutez un HttpRequestMessage initialisé avec un verbe PUT. Le code suivant est similaire à celui qui est utilisé pour créer une ressource :

HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Put, url);

message.Content = JsonContent.Create<Part>(part);

HttpResponseMessage response = await client.SendAsync(message);

Notes

La différence fondamentale entre POST et PUT est l’idempotence. Si vous répétez la même requête PUT plusieurs fois, la même ressource est mise à jour avec les mêmes données, et le résultat est le même que si vous aviez envoyé la requête une seule fois. Si vous émettez plusieurs fois la même requête POST, vous obtenez comme résultat le service REST qui crée plusieurs copies de la ressource.

Supprimer une ressource avec HttpClient

Pour supprimer une ressource en utilisant HttpClient, appelez SendAsync avec un HttpRequestMessage initialisé avec un verbe DELETE :

HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Delete, url);

HttpResponseMessage response = await client.SendAsync(message);

La réponse contient les en-têtes, le code d’état et l’objet supprimé.

Traiter les réponses d’une requête

Toutes les requêtes HTTP retournent un message de réponse. Les données figurant dans la réponse dépendent du verbe envoyé par l’application. Par exemple, le corps de la réponse d’une requête HTTP GET contient les données de la ressource demandée.

Le corps de la réponse d’une requête POST retourne une copie de la ressource qui a été créée, mais le corps de la réponse d’une requête PUT est en principe vide.

Vous devez toujours vérifier et traiter le code d’état dans le message de réponse. Si ce code d’état se trouve dans la plage 200 (200, 201, 202 et ainsi de suite), l’opération est considérée comme ayant réussi, même si des informations supplémentaires peuvent être nécessaires ultérieurement.

Un code d’état se trouvant dans la plage 300 indique que la requête a peut-être été redirigée par le service web vers une adresse différente, potentiellement en raison du déplacement d’une ressource vers un autre emplacement.

Un code d’état dans la plage 400 indique une erreur côté client ou application. Par exemple, le code d’état 403 signifie que le service web exige l’authentification de l’utilisateur, mais que l’application ne l’a pas fait. Le code d’état 404 se produit lorsque l’application tente d’accéder à une ressource qui n’existe pas.

Les codes d’état dans la plage 500 indiquent une erreur côté serveur, par exemple le service n’est pas disponible ou est trop occupé pour traiter la requête.

L’objet HttpResponseMessage retourné par une requête ayant été soumise par le biais d’un objet HttpClient peut réduire considérablement la complexité du traitement des différents codes d’état. Ce fragment de code montre comment vérifier que le code d’état dans un message de réponse indique la réussite et comment traiter les codes d’état qui indiquent une erreur.

static readonly HttpClient client = new HttpClient();

...
// Call asynchronous network methods in a try/catch block to handle exceptions.
try
{
    //... Initiate the HttpRequest

    HttpResponseMessage response = await client.SendAsync(msg);
    response.EnsureSuccessStatusCode(); // Check that the status code is in the 200 range. Throw an HttpRequestException if not
    
    string responseBody = await response.Content.ReadAsStringAsync();
    
    ... // Handle the response
}
catch(HttpRequestException e)
{
    ... // Handle any status codes that indicate an error. 
        // The status code is available in the field e.StatusCode
}

Contrôle des connaissances

Quel verbe HTTP devez-vous utiliser pour créer une ressource dans un service web REST ?

POST

PUT

ADD

Quelle méthode de la classe HttpResponseMessage devez-vous appeler pour vérifier qu’une requête HTTP a réussi ?

IsSuccessful

EnsureSuccessStatusCode

CheckStatusCode

Vous devez répondre à toutes les questions avant de vérifier votre travail.