Utiliser un service web basé sur REST

Parcourir l’exemple

REST (Representational State Transfer) est un style d’architecture pour la création de services web. Les requêtes REST sont généralement effectuées via HTTPS à l’aide des mêmes verbes HTTP que les navigateurs web utilisent pour récupérer des pages web et envoyer des données à des serveurs. Les verbes sont :

• GET : cette opération est utilisée pour récupérer des données auprès du service web.
• POST : cette opération est utilisée pour créer un nouvel élément de données sur le service web.
• PUT : cette opération est utilisée pour mettre à jour un élément de données sur le service web.
• PATCH : cette opération est utilisée pour mettre à jour un élément de données sur le service web en décrivant un ensemble d’instructions sur la façon dont l’élément doit être modifié.
• DELETE : cette opération est utilisée pour supprimer un élément de données sur le service web.

Les API de service web qui adhèrent à REST sont définies à l’aide des éléments suivants :

• URI de base.
• Des méthodes HTTP, comme GET, POST, PUT, PATCH ou DELETE.
• Type de média pour les données, tel que JavaScript Object Notation (JSON).

Les services web basés sur REST utilisent généralement des messages JSON pour retourner des données au client. JSON est un format d’échange de données textuel qui produit des charges utiles compactes, ce qui entraîne une réduction des exigences en bande passante lors de l’envoi de données. La simplicité de REST a aidé à le rendre la méthode principale pour accéder aux services web dans les applications mobiles.

Remarque

L’accès à un service web nécessite souvent une programmation asynchrone. Pour plus d’informations sur la programmation asynchrone, consultez Programmation asynchrone avec async et await.

Opérations de service web

L’exemple de service REST est écrit à l’aide de ASP.NET Core et fournit les opérations suivantes :

Opération	Méthode HTTP	URI relatif	Paramètres
Obtenir une liste d’éléments todo	GET	/api/todoitems/
Créer un élément todo	PUBLICATION	/api/todoitems/	Un objet TodoItem au format JSON
Mettre à jour un élément todo	PUT	/api/todoitems/	Un objet TodoItem au format JSON
Supprimer un élément todo	DELETE	/api/todoitems/{id}

L’application MAUI .NET et le service web utilisent la TodoItem classe pour modéliser les données affichées et envoyées au service web pour le stockage :

public class TodoItem
{
    public string ID { get; set; }
    public string Name { get; set; }
    public string Notes { get; set; }
    public bool Done { get; set; }
}

La ID propriété est utilisée pour identifier de manière unique chaque TodoItem objet et est utilisée par le service web pour identifier les données à mettre à jour ou supprimer. Par exemple, pour supprimer l’ID TodoItem dont l’ID est 6bb8a868-dba1-4f1a-93b7-24ebce87e243, l’application .NET MAUI envoie une demande DELETE à https://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243.

Lorsque l’infrastructure d’API web reçoit une requête, elle achemine la requête vers une action. Ces actions sont des méthodes publiques dans la TodoItemsController classe. L’infrastructure d’API web utilise l’intergiciel de routage pour faire correspondre les URL des requêtes entrantes et les mapper aux actions. Les API REST doivent utiliser le routage des attributs pour modéliser la fonctionnalité de l’application en tant qu’ensemble de ressources dont les opérations sont représentées par des verbes HTTP. Le routage par attributs utilise un ensemble d’attributs pour mapper les actions directement aux modèles de routes. Pour plus d’informations sur le routage des attributs, consultez Routage des attributs pour les API REST. Pour plus d’informations sur la création du service REST à l’aide de ASP.NET Core, consultez Création de services principaux pour les applications mobiles natives.

Créer l’objet HTTPClient

Une application d’interface utilisateur d’application multiplateforme .NET (.NET MAUI) peut consommer un service web BASÉ sur REST en envoyant des requêtes au service web avec la HttpClient classe. Cette classe fournit des fonctionnalités permettant d’envoyer des requêtes HTTP et de recevoir des réponses HTTP à partir d’une ressource identifiée par l’URI. Chaque requête est envoyée en tant qu’opération asynchrone.

L’objet HttpClient doit être déclaré au niveau de la classe afin qu’il se trouve tant que l’application doit effectuer des requêtes HTTP :

public class RestService
{
    HttpClient _client;
    JsonSerializerOptions _serializerOptions;

    public List<TodoItem> Items { get; private set; }

    public RestService()
    {
        _client = new HttpClient();
        _serializerOptions = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = true
        };
    }
    ...
}

L’objet JsonSerializerOptions est utilisé pour configurer la mise en forme de la charge utile JSON reçue et envoyée au service web. Pour plus d’informations, consultez Comment instancier des instances JsonSerializerOptions avec System.Text.Json.

Récupérer des données

La HttpClient.GetAsync méthode est utilisée pour envoyer une requête GET au service web spécifié par l’URI, puis recevoir la réponse du service web :

public async Task<List<TodoItem>> RefreshDataAsync()
{
    Items = new List<TodoItem>();

    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));
    try
    {
        HttpResponseMessage response = await _client.GetAsync(uri);
        if (response.IsSuccessStatusCode)
        {
            string content = await response.Content.ReadAsStringAsync();
            Items = JsonSerializer.Deserialize<List<TodoItem>>(content, _serializerOptions);
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }

    return Items;
}

Les données sont reçues du service web en tant qu’objet HttpResponseMessage . Il contient des informations sur la réponse, notamment le code d’état, les en-têtes et le corps du message. Le service REST envoie un code d’état HTTP dans sa réponse, qui peut être obtenu à partir de la HttpResponseMessage.IsSuccessStatusCode propriété, pour indiquer si la requête HTTP a réussi ou échoué. Pour cette opération, le service REST envoie le code d’état HTTP 200 (OK) dans la réponse, ce qui indique que la demande a réussi et que les informations demandées se situent dans la réponse.

Si l’opération HTTP a réussi, le contenu de la réponse est lu. La HttpResponseMessage.Content propriété représente le contenu de la réponse et est de type HttpContent. La HttpContent classe représente le corps HTTP et les en-têtes de contenu, tels que Content-Type et Content-Encoding. Le contenu est ensuite lu dans une string méthode à l’aide de la HttpContent.ReadAsStringAsync méthode. Il string est ensuite désérialisé de JSON vers un List objet TodoItem .

Avertissement

L’utilisation de la ReadAsStringAsync méthode pour récupérer une réponse volumineuse peut avoir un impact négatif sur les performances. Dans de telles circonstances, la réponse doit être désérialisée directement pour éviter d’avoir à le mettre entièrement en mémoire tampon.

Créer un flux

La HttpClient.PostAsync méthode est utilisée pour envoyer une requête POST au service web spécifié par l’URI, puis pour recevoir la réponse du service web :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));

    try
    {
        string json = JsonSerializer.Serialize<TodoItem>(item, _serializerOptions);
        StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = null;
        if (isNewItem)
            response = await _client.PostAsync(uri, content);
        else
            response = await _client.PutAsync(uri, content);

        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully saved.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

Dans cet exemple, l’instance TodoItem est sérialisée dans une charge utile JSON pour l’envoi au service web. Cette charge utile est ensuite incorporée dans le corps du contenu HTTP qui sera envoyé au service web avant l’envoi de la requête avec la PostAsync méthode.

Le service REST envoie un code d’état HTTP dans sa réponse, qui peut être obtenu à partir de la HttpResponseMessage.IsSuccessStatusCode propriété, pour indiquer si la requête HTTP a réussi ou échoué. Les réponses classiques pour cette opération sont les suivantes :

• 201 (CREATED) : la demande a entraîné la création d’une nouvelle ressource avant l’envoi de la réponse.
• 400 (DEMANDE INCORRECTE) : la demande n’est pas comprise par le serveur.
• 409 (CONFLIT) : la demande n’a pas pu être effectuée en raison d’un conflit sur le serveur.

Mettre à jour des données

La HttpClient.PutAsync méthode est utilisée pour envoyer une requête PUT au service web spécifié par l’URI, puis recevoir la réponse du service web :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  response = await _client.PutAsync(uri, content);
  ...
}

L’opération de la PutAsync méthode est identique à la PostAsync méthode utilisée pour créer des données dans le service web. Toutefois, les réponses possibles envoyées à partir du service web diffèrent.

Le service REST envoie un code d’état HTTP dans sa réponse, qui peut être obtenu à partir de la HttpResponseMessage.IsSuccessStatusCode propriété, pour indiquer si la requête HTTP a réussi ou échoué. Les réponses classiques pour cette opération sont les suivantes :

• 204 (NO CONTENT) : la demande a été traitée avec succès et la réponse est intentionnellement vide.
• 400 (DEMANDE INCORRECTE) : la demande n’est pas comprise par le serveur.
• 404 (INTROUVABLE) : la ressource demandée n’existe pas sur le serveur.

Supprimer des données

La HttpClient.DeleteAsync méthode est utilisée pour envoyer une requête DELETE au service web spécifié par l’URI, puis recevoir la réponse du service web :

public async Task DeleteTodoItemAsync(string id)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, id));

    try
    {
        HttpResponseMessage response = await _client.DeleteAsync(uri);
        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully deleted.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

Le service REST envoie un code d’état HTTP dans sa réponse, qui peut être obtenu à partir de la HttpResponseMessage.IsSuccessStatusCode propriété, pour indiquer si la requête HTTP a réussi ou échoué. Les réponses classiques pour cette opération sont les suivantes :

• 204 (NO CONTENT) : la demande a été traitée avec succès et la réponse est intentionnellement vide.
• 400 (DEMANDE INCORRECTE) : la demande n’est pas comprise par le serveur.
• 404 (INTROUVABLE) : la ressource demandée n’existe pas sur le serveur.

Développement local

Si vous développez un service web REST localement avec une infrastructure telle que ASP.NET’API web Core, vous pouvez déboguer votre service web et votre application MAUI .NET en même temps. Dans ce scénario, pour utiliser votre service web via HTTP à partir d’émulateurs Android et de simulateurs iOS, vous devez activer le trafic HTTP en texte clair dans votre application MAUI .NET. Pour plus d’informations, consultez Connecter aux services web locaux à partir d’émulateurs Android et de simulateurs iOS.