Meilleures pratiques pour l’implémentation de l’API web RESTful

Cet article décrit les meilleures pratiques pour l’implémentation, le déploiement et l’exploitation d’une API web RESTful. Il se concentre sur la gestion des demandes, les performances, la fiabilité, la publication et la supervision. Pour obtenir des conseils sur la modélisation des ressources et la conception d’API, consultez la conception d’API web.

Les conseils architecturaux s’appliquent aux langages et frameworks d’implémentation. Les exemples C# illustrent les contrôleurs ASP.NET Core.

Traitement des requêtes

Lorsque vous implémentez le code de traitement des requêtes, tenez compte des points ci-après.

Conserver la sémantique des méthodes HTTP et implémenter l’idempotence

Utilisez GET pour retourner des données de ressource et HEAD pour renvoyer des en-têtes de réponse sans corps. N’utilisez aucune des deux méthodes pour créer, mettre à jour ou supprimer des ressources.

GET, HEAD, PUT et DELETE doivent être idempotents. Par conséquent, la répétition d’une requête identique a le même effet que l’exécution de celle-ci une seule fois. Par exemple, DELETE modifie l’état d’une ressource, mais le répéter ne supprime pas de ressources supplémentaires. La première requête DELETE peut renvoyer 204 (aucun contenu), tandis qu’une requête suivante retourne 404 (introuvable).

POST et PATCH ne sont pas intrinsèquement idempotents. Une opération PATCH qui définit une propriété à une valeur peut être idempotente, mais une opération qui incrémente un compteur n’est pas. Documentez les opérations modifiant l’état que les clients peuvent réessayer en toute sécurité. Si vous prenez en charge les nouvelles tentatives pour les opérations qui ne sont pas naturellement idempotentes, implémentez et documentez la façon dont le service empêche les effets dupliqués. Pour connaître la sémantique des méthodes, consultez les méthodes de requête HTTP.

Valider les données de demande et contrôler l’accès aux champs

Définissez des modèles de demande et de réponse qui exposent uniquement les champs du contrat d’API. Associez ces modèles aux données stockées au lieu de lier des corps de requête HTTP directement aux entités de base de données ou de renvoyer toutes les propriétés stockées. Empêcher les appelants de modifier les propriétés protégées en envoyant des champs supplémentaires et omettre les propriétés qu’ils ne sont pas autorisés à lire. Les objets de transfert de données (DTO) sont un moyen d’appliquer cette délimitation. Pour plus d’informations, consultez Empêcher la sur-publication dans ASP.NET Core.

Validez les champs obligatoires, les types, les plages et les règles métier avant d’enregistrer les modifications. Si vous prenez en charge la sélection de champs, validez les champs demandés au regard d’une liste d’autorisation et des autorisations de l’appelant avant de projeter la réponse. Appliquez également des limites documentées au filtrage et au tri. Pour connaître les choix de contrat correspondants, consultez Pagination et filtrage.

Limiter les effets secondaires des actions POST qui créent des ressources

Lorsqu’une requête POST crée une ressource, limitez ses effets à cette ressource et aux ressources directement associées. Par exemple, la création d’une commande peut également mettre à jour l’inventaire et générer des informations de facturation. Il ne doit pas modifier les informations non liées.

Évitez d’implémenter des opérations POST, PUT et DELETE effectuant de nombreux échanges

Évitez de concevoir votre API en fonction d’opérations chatty. Chaque requête implique un surcoût lié au protocole, au réseau et au calcul. Par exemple, l’exécution de 100 requêtes plus petites au lieu d’une demande de traitement par lots plus volumineuse entraîne une surcharge supplémentaire dans le client, sur le réseau et sur le serveur de ressources. Pour les charges de travail qui ont besoin d’opérations en bloc, envisagez des demandes de traitement par lots limitées au lieu de nombreuses requêtes individuelles.

• Une requête GET à une collection peut récupérer plusieurs ressources en même temps.
• Une requête POST peut contenir les détails de plusieurs nouvelles ressources et les ajouter toutes à la même collection.
• Une requête PUT peut remplacer l’ensemble des ressources dans une collection.
• Une requête DELETE peut supprimer une collection entière.

Définissez les tailles de lots maximales, les tailles de charge utile, les temps d’exécution et le parallélisme. Spécifiez si un lot est atomique ou peut réussir partiellement et retourner un résultat pour chaque opération. Autorisez et validez chaque opération dans le lot.

Si vous utilisez OData, vous pouvez utiliser ASP.NET Core OData pour implémenter des requêtes par lots. Pour plus d’informations, consultez ASP.NET Core vue d’ensemble de OData.

Suivez la spécification HTTP lors de l’envoi d’une réponse

Retournez le code d’état HTTP, les en-têtes et le format de corps appropriés afin que les clients puissent interpréter et gérer la réponse.

Par exemple, une opération POST qui crée une ressource de manière synchrone doit retourner 201 (Créé) et identifier la ressource dans l’en-tête de réponse Location. Une opération qui accepte le travail pour un traitement ultérieur peut retourner 202 (Accepté), mais cette réponse n’indique pas que le travail a réussi. N’incluez pas de corps de réponse avec 204 (aucun contenu) ou 304 (non modifié). Pour plus d’informations, consultez les méthodes de requête HTTP.

Prenez en charge la négociation de contenu

Un corps de réponse peut contenir des données dans différents formats, tels que JSON ou XML. Les clients peuvent utiliser l’en-tête de requête Accept pour spécifier les types de média pris en charge. Par exemple, un client qui demande une image peut spécifier image/jpeg, image/gif, image/png. Retournez une représentation prise en charge et identifiez son type de média dans l’en-tête de la réponse Content-Type.

Si le client ne spécifie pas d’en-tête Accept , utilisez un format par défaut documenté. Les contrôleurs ASP.NET Core utilisent des formateurs JSON par défaut. Définissez ce qui se passe quand l’API ne peut pas produire de représentation demandée. Par exemple, configurez l’API pour retourner 406 (non acceptable) plutôt que de retourner silencieusement un format non pris en charge. Pour plus d’informations, consultez Mettre en forme les données de réponse dans ASP.NET Core API web.

Pour les demandes avec un corps, vérifiez le Content-Type de la requête et acceptez uniquement les formats pris en charge par l’opération. Retourne 415 (type de média non pris en charge) pour un format non pris en charge. Cette vérification est distincte de la négociation de réponse via Accept. Dans ASP.NET Core, configurez les formateur d'entrée et utilisez [Consumes] quand vous devez restreindre les formats de requête d'une opération. Pour plus d’informations, consultez Créer des API web avec ASP.NET Core.

Implémenter la stratégie de contrôle de version d’API sélectionnée

Appliquez la stratégie de versionnage que vous avez choisie lors de la conception de manière cohérente dans l’application et la passerelle. Achemine les demandes vers le gestionnaire et le schéma de réponse pour la version sélectionnée. Définissez le comportement à adopter en cas d’identificateurs de version omis, mal formés ou non pris en charge plutôt que de modifier silencieusement le contrat qu’un appelant existant reçoit.

Conservez les contrats de requête et de réponse des versions prises en charge. Lorsque vous introduisez un changement incompatible, fournissez une nouvelle version et conservez les versions antérieures prises en charge. Gérez les requêtes des anciens appelants qui omettent les champs facultatifs récemment ajoutés. Pour plus d’informations, consultez Gestion des versions et compatibilité des API.

Conservez les liens de ressources générés et les représentations mises en cache cohérentes avec la version sélectionnée. Pour le contrôle de version basé sur l’en-tête, assurez-vous que les caches distinguent les demandes pour différentes versions au lieu de s’appuyer uniquement sur l’URI.

Résoudre et autoriser le contexte de locataire

Pour une API multilocataire, déterminez le locataire de chaque requête et vérifiez que l’appelant authentifié peut accéder à ce locataire. Traitez les identificateurs de locataire dans les chemins, les noms d’hôte et les en-têtes comme des entrées de routage uniquement. Pour plus d’informations, consultez Mapper des requêtes à des locataires dans une solution multi-locataire.

Utilisez le contexte de tenant autorisé de manière cohérente lors de l’interrogation ou de la mise à jour des données et lors de la transmission du travail à des processus en arrière-plan. Si les caches d’application ou de passerelle stockent des données spécifiques au locataire, incluez l’identificateur du locataire dans la clé de cache. Pour obtenir des conseils spécifiques à la passerelle, consultez les fonctionnalités d’API Management qui prennent en charge l’architecture mutualisée.

Fournissez des liens afin d’assurer la prise en charge de la navigation de type HATEOAS et la découverte des ressources

L’hypertexte en tant que moteur d’état d’application (HATEOAS) utilise des liens pour aider les clients à découvrir et à parcourir les ressources. Par exemple, une réponse qui contient les détails du client peut inclure des liens vers les commandes de ce client. Décrivez les opérations que chaque ressource liée prend en charge, telles que GET, POST, PUT et DELETE, et fournissez les URI correspondants. Pour plus d’informations, consultez la conception d’API.

L’exemple suivant utilise une représentation de lien définie par l’application. Documentez les conventions utilisées plutôt que de supposer que les clients peuvent interpréter des champs de lien personnalisés. Une demande GET pour un client retourne des liens vers les commandes de ce client :

GET https://api.contoso.com/customers/2 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
...
Content-Type: application/json; charset=utf-8
...
Content-Length: ...
{"customerId": 2,"customerName": "Bert","links": [
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "PUT",
     "types": ["application/x-www-form-urlencoded"]},
    {"rel": "self",
     "href": "https://api.contoso.com/customers/2",
     "action": "DELETE",
     "types": []},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "GET",
     "types": ["text/xml","application/json"]},
    {"rel": "orders",
     "href": "https://api.contoso.com/customers/2/orders",
     "action": "POST",
     "types": ["application/x-www-form-urlencoded"]}
]}

L’enregistrement suivant Customer représente les données client. Sa Links propriété contient les liens HATEOAS.

public sealed record Customer(
    int CustomerId,
    string CustomerName,
    IReadOnlyList<Link> Links);

public sealed record Link(
    string Rel,
    string Href,
    string Action,
    IReadOnlyList<string> Types);

L’opération GET récupère les données client à partir du stockage, construit un enregistrement Customer avec ses liens et retourne une réponse JSON. Chaque lien comprend les champs suivants :

• Relation (Rel) entre la ressource retournée et la ressource liée. Dans cet exemple, self fait référence au client et orders fait référence à la collection de commandes du client.
• Lien hypertexte (Href) de l’objet décrit par le lien, sous la forme d’un URI.
• Type de requête HTTP (Action) qui peut être envoyée à l’URI.
• Le format des données (Types) qui doit être fourni dans la requête HTTP ou qui peut être renvoyé dans la réponse, en fonction du type de la requête.

Les liens HATEOAS représentés dans l’exemple de réponse HTTP indiquent qu’une application cliente peut exécuter les opérations suivantes :

• Requête HTTP GET vers https://api.contoso.com/customers/2 pour récupérer les détails du client au format XML ou JSON.
• Demande HTTP PUT pour https://api.contoso.com/customers/2 modifier les détails du client. Le corps de la requête utilise ce format : application/x-www-form-urlencoded.
• Requête HTTP DELETE via https://api.contoso.com/customers/2 pour supprimer l’enregistrement client. Cette opération ne nécessite aucun corps de requête et ne retourne aucun corps de réponse.
• Requête HTTP GET vers https://api.contoso.com/customers/2/orders pour récupérer les commandes du client en XML ou JSON.
• Requête HTTP POST vers https://api.contoso.com/customers/2/orders pour créer une commande pour le client. Le corps de la requête utilise ce format : application/x-www-form-urlencoded.

Gestion des exceptions

Si une opération lève une exception qui n’est pas gérée, tenez compte des instructions suivantes.

Capturez les exceptions et renvoyez une réponse pertinente aux clients

Gérez les exceptions de manière cohérente et retournez une réponse d’erreur pertinente pouvant être partagée sans risque avec les clients. Ne retournez pas d’objets d’exception, de traces de pile ou de détails d’implémentation interne dans les réponses de production. Retourne un code d’état HTTP qui reflète l’échec au lieu de retourner le code d’état 500 pour chaque situation. Par exemple, si une demande d’utilisateur provoque une mise à jour de base de données qui enfreint une contrainte (telle que la tentative de suppression d’un client qui a des commandes en attente), renvoyez le code 409 (Conflit) avec une explication appropriée. Retourne 400 (demande incorrecte) pour une entrée malformée ou des échecs de validation de requête, et non pour les défaillances inattendues du serveur. Pour connaître les définitions d’état HTTP, consultez Codes d’état. Pour obtenir des conseils d’implémentation, consultez Gérer les erreurs dans ASP.NET Core.

Le contrôleur suivant mappe les résultats de domaine attendus aux réponses HTTP. Son opération de référentiel vérifie l’autorisation et les commandes en attente dans le cadre de l’opération de suppression. Les défaillances inattendues se propagent à la gestion centralisée des exceptions au lieu d’être interceptées en mode silencieux dans chaque action.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("customers")]
public sealed class CustomersController(ICustomerRepository repository) : ControllerBase
{
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> DeleteCustomer(int id, CancellationToken cancellationToken)
    {
        var outcome = await repository.DeleteAuthorizedAsync(id, User, cancellationToken);

        return outcome switch
        {
            DeleteOutcome.Deleted => NoContent(),
            DeleteOutcome.NotFound => NotFound(),
            DeleteOutcome.HasOutstandingOrders => Conflict(new ProblemDetails
            {
                Status = StatusCodes.Status409Conflict,
                Title = "The customer has outstanding orders."
            }),
            _ => throw new InvalidOperationException("Unknown deletion outcome.")
        };
    }
}

public enum DeleteOutcome
{
    Deleted,
    NotFound,
    HasOutstandingOrders
}

La couche d’hébergement peut rejeter les demandes avant qu’elles n’atteignent l’API. Par exemple, les échecs d’authentification peuvent entraîner des réponses 401 (non autorisées). Après l’authentification, vérifiez que l’appelant est autorisé à accéder à la ressource demandée. Retourne 403 (Interdit) en cas d’échec de l’autorisation d’accès.

Gérez les exceptions de manière cohérente et consignez les informations sur les erreurs

Pour gérer les exceptions de manière cohérente, envisagez d’implémenter une stratégie globale de gestion des erreurs sur l’ensemble de l’API web. Consignez les informations de diagnostic sur le serveur, mais excluez les secrets, les jetons d’accès et les données personnelles sensibles. Masquez les valeurs sensibles avant d’écrire des entrées de journal et limitez l’accès au journal aux utilisateurs autorisés. Pour plus d’informations, consultez Stratégies d’architecture pour la surveillance et la détection des menaces.

Dans ASP.NET Core, utilisez un middleware de gestion des exceptions et des réponses Problem Details pour un contrat d’erreur cohérent. Configurez les réponses de production pour omettre les détails de diagnostic et incluez un identificateur de corrélation que les équipes de support peuvent utiliser pour localiser les journaux correspondants. Pour plus d’informations, consultez Gérer les erreurs dans ASP.NET Core.

Différenciez les erreurs côté client des erreurs côté serveur

Utilisez les codes d’état HTTP 4xx pour les erreurs du client et les codes d’état HTTP 5xx pour les erreurs de serveur. Conservez cette distinction dans les réponses d’erreur.

Optimisation de l’accès aux données côté client

Les requêtes fréquentes et les réponses volumineuses peuvent rendre le réseau un goulot d’étranglement. Réduisez les transferts inutiles lorsque vous implémentez la récupération et les mises à jour des ressources.

Prenez en charge la mise en cache côté client

Utilisez l’en-tête Cache-Control de réponse pour spécifier si les clients et les serveurs intermédiaires peuvent stocker une réponse et combien de temps elle reste fraîche.

L’exemple suivant représente une requête HTTP GET et la réponse correspondante, qui comporte un en-tête Cache-Control :

GET https://api.contoso.com/orders/2 HTTP/1.1

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

Dans cet exemple, la réponse reste actuelle pendant 600 secondes. La private directive autorise le stockage dans un cache privé, tel qu’un cache de navigateur, mais interdit le stockage dans un cache partagé. Utilisez public uniquement pour les réponses que l’on peut partager en toute sécurité entre les appelants. Utiliser no-store pour les réponses sensibles qui ne doivent pas être stockées.

Dans un contrôleur ASP.NET Core, définissez les en-têtes de cache avant de renvoyer la réponse :

Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue
{
    Private = true,
    MaxAge = TimeSpan.FromMinutes(10)
};

L’API contrôle la stratégie de cache et les validateurs dans ses réponses. Les clients et les serveurs intermédiaires utilisent ces informations pour gérer leurs caches. Définissez ces en-têtes de manière cohérente afin que les appelants puissent réutiliser les réponses sans transferts de données inutiles.

Pour déterminer max-age, tenez compte du niveau d’obsolescence que la charge de travail peut tolérer. Une ressource peut changer alors qu’une réponse mise en cache est toujours fraîche. Lorsque la période d'actualité expire, un cache peut revalider la réponse au lieu de la rejeter et télécharger à nouveau la représentation entière. N’utilisez pas un long délai pour les données qui nécessitent une visibilité immédiate des modifications.

Fournissez des éléments ETag afin d’optimiser le traitement des requêtes

Une balise d’entité (ETag) est un validateur opaque pour une représentation de ressource sélectionnée. Les clients peuvent le conserver avec une réponse mise en cache et l’envoyer dans If-None-Match pour vérifier si la représentation a changé. Une requête GET ou HEAD correspondante retourne 304 (non modifié) sans corps de réponse.

Générez un validateur qui reste cohérent entre les instances d’application et qui change lorsque la représentation change.

Le contrôleur suivant hache les octets JSON exacts qu’il retourne et réutilise les options JSON configurées de l’application. FileContentResult applique la gestion ASP.NET Core des réponses conditionnelles sans wrappers de résultats personnalisés. Le référentiel retourne uniquement un ordre que l’appelant est autorisé à lire. Configurez l’authentification et l’autorisation dans l’application hôte.

using System.Security.Cryptography;
using System.Text.Json;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using Microsoft.Net.Http.Headers;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrdersController(IOrderRepository repository,IOptions<JsonOptions> jsonOptions) : ControllerBase
{
    [HttpGet("{id:int}")]
    [HttpHead("{id:int}")]
    public async Task<IActionResult> GetOrder(int id, CancellationToken cancellationToken)
    {
        var order = await repository.FindAuthorizedAsync(id, User, cancellationToken);
        if (order is null)
        {
            return NotFound();
        }

        var payload = JsonSerializer.SerializeToUtf8Bytes(order, jsonOptions.Value.JsonSerializerOptions);
        var etag = new EntityTagHeaderValue($"\"{Convert.ToHexString(SHA256.HashData(payload))}\"");

        Response.GetTypedHeaders().CacheControl = new CacheControlHeaderValue
        {
            Private = true,
            MaxAge = TimeSpan.FromMinutes(10)
        };

        return new FileContentResult(payload, "application/json")
        {
            EntityTag = etag
        };
    }
}

Cet exemple met en mémoire tampon la représentation et lit l’entité même pour une requête conditionnelle. Utilisez-le uniquement pour les réponses cadrées et non sensibles. Pour les ressources volumineuses, envisagez d’utiliser un jeton de version stocké qui change chaque fois que la représentation sélectionnée change, afin de pouvoir valider une requête sans générer la charge utile complète. Si la négociation de contenu, la compression ou les transformations de passerelle modifient la représentation, assurez-vous que les validateurs et les variantes de cache restent corrects pour cette représentation.

Une réponse inclut l’ETag et la stratégie de mise en cache. Les exemples suivants montrent les 16 premiers caractères hexadécimaux (64 bits) du hachage SHA-256 du corps JSON affiché, suivis de ... pour plus de concision. Les en-têtes réels contiennent le hachage complet sans les points de suspension.

HTTP/1.1 200 OK
...
Cache-Control: max-age=600, private
Content-Type: application/json
ETag: "3097D1FD51082205..."
Content-Length: 59

{"orderId":2,"productId":4,"quantity":2,"orderValue":10.00}

Prendre en charge les requêtes GET conditionnelles afin que les appelants puissent revalider les réponses mises en cache sans retélécharger la représentation si elle n’a pas changé. Implémentez le comportement de requête et de réponse suivant :

1. Acceptez les requêtes GET conditionnelles qui fournissent un ETag dans l’en-tête If-None-Match , par exemple :

   GET https://api.contoso.com/orders/2 HTTP/1.1
   If-None-Match: "3097D1FD51082205..."
   

2. Comparez l’ETag actuel de la ressource demandée (ordre 2 dans cet exemple) avec la condition If-None-Match.

   • Si la condition est remplie, retournez 304 (non modifié) sans corps de réponse.

   • Si la condition ne correspond pas, retournez 200 (OK) avec la représentation actuelle.

   • Si la ressource demandée n’existe plus, retournez 404 (introuvable).

Utilisez la prise en charge du framework pour les demandes conditionnelles si possible. Si vous implémentez des comparaisons vous-même, gérez toutes les balises d’entité fournies, les conditions avec caractère générique et les règles de comparaison faibles et fortes plutôt que de comparer uniquement la première balise. Incluez les en-têtes ETag et cache appropriés sur les réponses 304 (non modifiées) et effectuez l’autorisation avant de retourner les métadonnées de ressource.

Utiliser des ETags pour prendre en charge la gestion de la concurrence optimiste

Pour éviter les mises à jour perdues, évaluez les conditions préalables If-Match sur les requêtes modifiant l’état par rapport à l’ETag actuel de la ressource. Cela permet à l’API de rejeter une modification en fonction d’une représentation qu’une autre opération a déjà modifiée. Implémentez le comportement suivant :

1. Acceptez les demandes de mise à jour qui identifient la version attendue dans l’en-tête If-Match . La requête PUT suivante met à jour la commande 2. Il utilise l’ETag, abrégé de la même façon, de la réponse GET précédente. La balise identifie la représentation existante, et non le nouveau corps de la demande :

   PUT https://api.contoso.com/orders/2 HTTP/1.1
   If-Match: "3097D1FD51082205..."
   Content-Type: application/x-www-form-urlencoded
   Content-Length: 37
   
   productId=3&quantity=5&orderValue=250
   

2. Comparez l’ETag actuel de la ressource demandée (ordre 2 dans cet exemple) avec la condition If-Match.

   • Si la condition préalable correspond, effectuez la mise à jour atomiquement et retournez la réponse de réussite documentée, telle que 204 (Aucun contenu). Un Location en-tête n’est pas nécessaire simplement parce qu’une ressource existante a été mise à jour. Retournez uniquement un ETag dans une réponse PUT réussie lorsqu'il répond aux exigences du validateur HTTPS pour la représentation stockée.

   • Si la condition ne correspond pas, retourne 412 (Échec de la condition préalable). Cet exemple ne retourne aucun corps de réponse.

   • Si la ressource à mettre à jour n’existe plus, retournez 404 (introuvable).

3. Documentez les réponses de réussite et de conflit afin que les appelants puissent déterminer si une mise à jour a réussi ou s’ils doivent récupérer la représentation actuelle avant d’envoyer une autre modification.

Pour les opérations qui doivent empêcher les mises à jour perdues, exiger une condition préalable If-Match et retourner 428 (Condition préalable requise) lorsqu’elle est absente. Utilisez une comparaison stricte pour If-Match.

La vérification d’une version dans la mémoire de l’application, puis l’enregistrement sans condition crée une condition de concurrence. Appliquez la comparaison de versions et l’écriture atomiquement dans le magasin de données. Par exemple, utilisez un jeton de concurrence de base de données pour que la mise à jour réussisse uniquement si la version stockée correspond toujours à la version utilisée pour évaluer la requête.

Dans Entity Framework (EF) Core, configurez un jeton de concurrence et gérez DbUpdateConcurrencyException plutôt que de remplacer une modification simultanée. Dans le code d’accès aux données de l’API, ne remplacez pas automatiquement la version attendue ni ne réessayez une mise à jour de base de données en conflit, sauf si la sémantique de l’opération l’autorise. Pour plus d’informations, consultez Gestion des conflits d’accès concurrentiel.

Gestion des requêtes et des réponses de taille importante

Les corps de requête et de réponse volumineux consomment la mémoire de l’API, la bande passante et la capacité de connexion. Implémentez des limites de streaming et de ressources afin que les transferts volumineux n’épuisent pas le service. Tenez compte des points suivants lors de la gestion de quantités importantes de données :

Optimisez les requêtes et les réponses impliquant des objets volumineux

Pour les objets volumineux, tels que les images ou d’autres données binaires, prendre en charge les chargements et téléchargements en continu.

Utilisez des API de diffusion en continu asynchrones et laissez le serveur sélectionner le mode de délimitation du transfert pour la version HTTP négociée. N’ajoutez pas manuellement Transfer-Encoding: chunked à chaque élément d’une réponse. La diffusion en continu n’est pas limitée à l’encodage par morceaux HTTP/1.1. Évitez de mettre en mémoire tampon l’intégralité d’une requête ou d’une réponse non limitée dans la mémoire de l’application.

Définissez les limites du corps de la requête, les limites de chargement, les délais d’expiration et les stratégies d’annulation au niveau des couches d’application et d’hébergement. Rejeter une demande surdimensionnée avec 413 (Contenu trop volumineux) avant de démarrer la réponse.

La compression HTTP peut réduire la taille de transfert, au coût d’un traitement supplémentaire sur le serveur et le client. Par exemple, un client peut envoyer Accept-Encoding: gzip. Si le serveur retourne du contenu compressé par gzip, identifiez l’encodage à l’aide de Content-Encoding: gzip.

Configurez la compression par le biais de la plateforme d’hébergement ou de l’intergiciel et mesurez ses compromis de processeur et de bande passante côté client et serveur.

• Évitez de recomprimer les formats déjà compressés.
• Avant d’activer la compression pour les réponses HTTPS générées dynamiquement, évaluez les risques de compression, tels que BREACH, et appliquez les atténuations appropriées. Même si vous désactivez la compression HTTPS dans votre intergiciel, votre serveur d’hébergement peut être configuré pour appliquer la compression.
• Vérifiez que les variantes de cache et les ETags restent corrects lorsque l’encodage du contenu change.

Pour obtenir des conseils sur l’implémentation de compression et des considérations de sécurité, consultez la compression de la réponse dans ASP.NET Core.

Prise en charge des téléchargements partiels de ressources volumineuses

Si l’API prend en charge les téléchargements partiels de ressources volumineuses, signalez cette capacité avec Accept-Ranges. Gérez les requêtes HEAD en retournant les métadonnées de la ressource, y compris son total Content-Length, sans corps de réponse. Pour les requêtes GET qui spécifient une plage d’octets prise en charge, retournez 206 (Contenu partiel), une Content-Length pour la partie retournée et une Content-Range qui identifie cette partie de la ressource. Ce contrat de réponse permet aux appelants de récupérer des parties d’une ressource sans exiger que l’API retourne l’objet entier.

Les requêtes HTTP HEAD et les réponses partielles sont décrites plus en détail dans le guide de conception d’API.

Gérer 100-Continue pour les chargements volumineux

Pour un chargement HTTP/1.1 volumineux, un client peut envoyer des en-têtes de requête avec Expect: 100-continue et attendre avant de transmettre le corps. Le serveur peut envoyer une réponse intermédiaire 100 (Continuer) ou rejeter la demande sans recevoir le corps complet. Cet échange fait partie d’une seule demande, et non d’une demande vide préliminaire suivie d’une deuxième demande complète.

Configurez et testez la façon dont la pile d’hébergement et la passerelle gèrent les requêtes avec et sans Expect: 100-continue. Vérifiez le comportement de l’API lorsqu’elle accepte ou rejette un téléversement et mesurez les effets sur l’utilisation des ressources du serveur et la latence de requête.

Prenez en charge la pagination pour les requêtes susceptibles de renvoyer de très nombreux objets

La récupération d’une collection volumineuse entière peut augmenter le traitement du serveur, le trafic réseau et la latence.

Validez les entrées de pagination sur le serveur et appliquez une taille de page maximale. Le contrôleur suivant illustre la validation des demandes. Sa valeur par défaut est de 10 résultats et elle rejette les limites en dehors de 1 à 100 ou les décalages en dehors de 0 à 10 000. Ces limites sont données à titre indicatif. Choisissez des limites en fonction de la charge de travail et des tests de charge. Lorsque vous utilisez [ApiController], les échecs de validation produisent une réponse de 400. Pour plus d’informations, consultez Créer des API web avec ASP.NET Core.

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Authorize]
[Route("orders")]
public sealed class OrderCollectionsController(IOrderRepository repository) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<IReadOnlyList<Order>>> GetOrders(
        [FromQuery, Range(1, 100)] int limit = 10,
        [FromQuery, Range(0, 10000)] int offset = 0,
        CancellationToken cancellationToken = default)
    {
        var orders = await repository.ListAuthorizedAsync(limit, offset, User, cancellationToken);
        return Ok(orders);
    }
}

Un client peut demander 30 commandes à partir du décalage 50 à l’aide de https://api.contoso.com/orders?limit=30&offset=50.

Au-delà de la validation de la demande indiquée dans l’exemple précédent, incluez un lien de page suivante ou un jeton de continuation dans le contrat de réponse. Par exemple, retournez les commandes avec une propriété nextLink définie sur https://api.contoso.com/orders?limit=30&offset=80 lorsqu’une autre page est disponible. Conservez les filtres, l’ordre de tri et la version de l’API dans le lien. Omettez nextLink ou définissez-le à null sur la dernière page. Pour obtenir un exemple de contrat nextLink, consultez Pagination Microsoft Graph.

Appliquez le filtrage et la pagination dans le magasin de données, et non après le chargement de la collection entière. Utilisez un ordre de tri déterministe. Pour les regroupements volumineux ou fréquemment modifiés, évaluez la pagination basée sur le curseur pour éviter les décalages coûteux et les limites de page instables.

Maintien de la réactivité, de l’extensibilité et de la disponibilité

Définissez les objectifs de latence, de débit et de disponibilité pour les opérations critiques de l’API. Concevez et testez en fonction du trafic attendu, des pics de charge et des défaillances des dépendances. La montée en charge horizontale et la gestion sans état permettent d’atteindre ces objectifs. Tenez compte des exigences d’implémentation suivantes.

Offrez une prise en charge asynchrone pour les requêtes de longue durée

Pour les tâches qui durent plus longtemps qu’une requête HTTP normale, validez et autorisez la requête, enregistrez durablement le travail et retournez 202 (accepté). Ne comptez pas sur une tâche en cours non suivie pour se terminer après une réponse : les redémarrages de l’application, la mise à l’échelle et le déploiement peuvent l’interrompre. Utilisez une file d’attente durable et un worker ou un flux de travail durable lorsque le travail doit continuer à s’exécuter malgré ces événements. Pour obtenir des instructions complètes sur la sémantique HTTP et l’implémentation, consultez le modèle de Request-Reply asynchrone.

Fournissez un moyen pour les appelants de récupérer l’état et le résultat de l’opération. L’API peut également avertir les appelants lorsque le traitement est terminé.

Vous pouvez fournir une ressource d’état que les clients interrogent :

1. Le client envoie la demande. Validez ses entrées et ses autorisations avant d’accepter le travail.
2. Conservez un identificateur d’opération et un état dans un stockage durable, tel que le stockage Table Azure, et mettez le travail en file d’attente pour un processeur distinct, par exemple en utilisant Azure Service Bus. Coordonner la persistance et la mise en file d’attente afin qu’une défaillance entre ces deux actions n’entraîne pas la perte de travail accepté.
3. Retourne 202 avec un Location en-tête qui identifie le point de terminaison d’état et un Retry-After en-tête qui contrôle la fréquence d’interrogation. Acceptez la demande uniquement une fois le travail enregistré de manière durable.
4. Un agent traite l’opération et met à jour son état durable. Effectuez un traitement idempotent, car un worker peut recevoir le même travail plusieurs fois. Appliquez des nouvelles tentatives limitées aux échecs temporaires.
5. Le client interroge le point de terminaison d’état. Appliquez l’autorisation au niveau des ressources sur les points de terminaison d’état et de résultat. Un identificateur impossible à deviner n’est pas une autorisation.
6. Renvoyez une représentation d'état documentée pendant que le travail est en cours. Une fois l’opération terminée, indiquez le résultat ou une redirection 303 (See Other) vers une ressource de résultat. Signaler les échecs via un contrat d’erreur cohérent et sécurisé.
7. Définissez la conservation et le nettoyage des enregistrements et des résultats des opérations. Documentez l'expiration des opérations, les soumissions en double et le comportement d’annulation pris en charge.

Pour les clients connectés, envisagez d’utiliser ASP.NET Core SignalR pour les notifications d’achèvement. Conservez la ressource d’état durable disponible afin que les clients puissent récupérer après une déconnexion ou une notification manquée. Pour plus d’informations, consultez Vue d’ensemble de ASP.NET Core SignalR.

Assurez-vous que chaque requête est sans état

N’exigez pas qu’une requête ultérieure atteigne la même instance d’application qu’une requête antérieure. Conservez le flux de travail et l’état des ressources dans les magasins partagés appropriés, et non uniquement dans la mémoire du processus. Les requêtes peuvent dépendre de l’état de ressource durable sans créer d’affinité avec une instance de serveur. La gestion des demandes sans état permet la montée en charge horizontale.

Comprendre vos dépendances en aval

Définissez un délai d’expiration pour chaque appel vers un service aval. Veillez à ce que la durée totale des appels, des nouvelles tentatives et des retards reste dans le délai de la requête API, et propagez l’annulation de la requête aux opérations en aval.

Réessayez uniquement les opérations ayant échoué de façon transitoire et les opérations qui peuvent être répétées sans risque. Utilisez un nombre limité de tentatives avec une temporisation progressive et de la gigue. Limitez le nombre total de tentatives par dépendance, ainsi que les tentatives par requête. Pour plus d’informations, consultez Gestion des erreurs transitoires.

Utilisez un disjoncteur lorsque des défaillances de dépendance répétées peuvent épuiser la capacité de l’API.

Suivez les clients et implémentez la limitation afin de réduire les risques d’attaques DoS

Définissez des limites de taux de requêtes, de concurrence, de charge utile et de durée d’exécution. Partitionnez les limites par appelant ou locataire authentifié, si possible. Retourne 429 (Trop de demandes) lorsqu’un appelant dépasse un taux configuré et 503 (Service indisponible) pour l’indisponibilité temporaire du service. Incluez Retry-After le cas échéant. Si l’API retente des appels aux dépendances en aval, limitez ces nouvelles tentatives afin qu’elles n’amplifient pas la surcharge.

Les limites de passerelle et d’application ont des finalités différentes. Les limites de passerelle peuvent protéger la capacité partagée. Les limites d’application peuvent refléter le coût d’opération et la capacité en aval. Aucun des deux ne remplace la protection DDoS de la couche réseau ou un pare-feu d’applications web. Pour plus d’informations, consultez le modèle de limitation.

Gérez prudemment les connexions HTTP persistantes

Pour les connexions entrantes, configurez les délais d’expiration du serveur et de la passerelle, les délais d’expiration des requêtes et les limites de connexion simultanées pour la charge de travail et le chemin d’accès réseau. Ne forcez pas systématiquement les connexions à fermer après chaque réponse. Pour plus d’informations sur les paramètres de serveur ASP.NET Core, consultez Configurer les options du serveur web Kestrel.

Si l’API elle-même appelle des services HTTP en aval, réutilisez ces connexions sortantes. Dans une implémentation d’API .NET, utilisez des instances de longue durée HttpClient avec un PooledConnectionLifetime approprié, ou utilisez des clients créés par IHttpClientFactory. Libérez les messages et les flux de réponse sortants lorsqu’ils ne sont plus nécessaires. Ces paramètres s’appliquent aux appels en aval de l’API, et non aux connexions clientes entrantes. Pour plus d’informations et des avertissements de gestion des cookies, consultez Instructions pour l’utilisation de HttpClient.

Publication et gestion d’une API web

Déployez l’API dans un environnement d’hébergement qui répond à ses exigences opérationnelles. Réfléchissez aux stratégies suivantes :

• utiliser le protocole HTTPS ; Authentifiez les demandes auprès des points de terminaison d’API protégés et appliquez le contrôle d’accès pour chaque ressource et opération.
• Adaptez l’environnement d’hébergement pour respecter les engagements en matière de temps de réponse à mesure que la demande change.
• Comptez les requêtes si le modèle de facturation de l’API l’exige.
• Réglez le trafic et appliquez les quotas client si nécessaire.
• Enregistrez les événements d’audit que la conformité et la réponse aux incidents exigent, mais ne journalisez pas les informations d’identification, les jetons ou les corps de demande et de réponse sensibles.
• Surveillez l’intégrité de l’hôte et définissez des actions de récupération, telles que le redémarrage d’un hôte défectueux.

Envisagez d’utiliser une façade distincte qui gère les problèmes de gestion partagée et transfère les demandes validées à l’API. Une façade peut fournir les fonctionnalités suivantes :

• apport d’un point d’intégration pour plusieurs API Web ;
• transformation des messages et traduction des protocoles de communication pour les clients développés à l’aide de technologies diverses ;
• mise en cache des requêtes et des réponses afin de réduire la charge sur le serveur hébergeant l’API Web.

Conservez les contrats d’API et la configuration de la passerelle sous contrôle de version, validez les modifications dans les pipelines de déploiement et définissez les procédures de restauration. Alignez l’hébergement, l’identité, la mise en réseau et la gouvernance avec l’approche de zone d'atterrissage de l’organisation. Pour plus d’informations, consultez Qu’est-ce qu’une zone d’atterrissage Azure ?.

Test d’une API web

Utilisez des tests unitaires pour valider la logique de l’API et des tests d’intégration pour vérifier son comportement HTTP.

Incluez les vérifications suivantes :

• Testez l’ensemble des itinéraires afin de vérifier qu’ils invoquent les opérations appropriées. Soyez particulièrement attentif au fait que le code d’état HTTP 405 (méthode non autorisée) est retourné de façon inattendue. Ce code d'état peut indiquer une incompatibilité entre une route et les méthodes HTTP (GET, POST, PUT, DELETE) qui peuvent être acheminées vers cette route.

  Envoyez des demandes qui utilisent des méthodes qui ne sont pas prises en charge par chaque route et vérifiez la réponse 405 (Méthode non autorisée) documentée et l’en-tête Allow documenté.

• Vérifiez que l’ensemble des itinéraires sont correctement protégés et font l’objet des contrôles d’autorisation et d’authentification appropriés.

  Remarque

  Certains aspects de la sécurité, tels que l’authentification utilisateur, sont susceptibles d’être la responsabilité de l’environnement hôte plutôt que de l’API web, mais vous devez toujours inclure des tests de sécurité dans le cadre du processus de déploiement.

• Testez le traitement des exceptions effectué par chaque opération et vérifiez qu’une réponse HTTP appropriée et pertinente est transmise à l’application cliente.

• Vérifiez que les requêtes et les messages de réponse sont correctement composés. Par exemple, pour une requête POST qui crée une ressource, vérifiez la désérialisation, l’analyse, la création de ressources et l’en-tête Location de la réponse.

• Testez les types de média de requête pris en charge et non pris en charge séparément de la négociation de contenu de réponse. Vérifiez les réponses 415 (type de média non pris en charge) pour les formats de requête non pris en charge et les erreurs de validation documentées pour les corps mal formés.

• Testez chaque version de l’API prise en charge, y compris son routage, sa validation de demande et son schéma de réponse. Testez les identificateurs de version omis, mal formés et non pris en charge et vérifiez que les réponses mises en cache ne franchissent pas les frontières entre versions.

• Vérifiez l’ensemble des liens et des URI des messages de réponse. Par exemple, un message HTTP POST doit renvoyer l’URI de la ressource nouvellement créée. Tous les liens HATEOAS doivent être valides.

• Assurez-vous que chaque opération renvoie les codes de statut appropriés pour différentes combinaisons d’entrée. Par exemple :

  • Si une requête réussit, elle doit retourner le code d’état 200 (OK).
  • Si une ressource est introuvable, l’opération doit retourner le code d’état HTTP 404 (introuvable).
  • Si le client transmet une requête qui supprime une ressource, le code de statut 204 doit être renvoyé (Aucun contenu).
  • Si le client transmet une requête qui crée une nouvelle ressource, le code de statut doit être 201 (Créé).

  Examinez les réponses inattendues 5xx de l’application ou de la couche d’hébergement.

• Testez les différentes combinaisons d’en-têtes de requêtes pouvant être définies par une application cliente et vérifiez que l’API Web renvoie les informations appropriées dans les messages de réponses transmis.

• Testez les chaînes de recherche. Si une opération peut prendre des paramètres facultatifs (tels que des demandes de pagination), testez les différentes combinaisons et l’ordre des paramètres.

• Vérifiez que les opérations asynchrones s’effectuent correctement Pour les réponses de streaming, vérifiez que l’API ne met pas en mémoire tampon l’intégralité de la charge utile et qu’elle gère correctement les déconnexions et l’annulation des clients. Si l’API fournit des ressources d’état pour les opérations de longue durée, vérifiez qu’elles signalent correctement la progression de l’opération et les résultats.

Testez les cas d’échec et de limite qui affectent l’exactitude :

• Validez les entrées minimales, maximales, négatives, incorrectes et excessives de pagination et de lot.
• Suivez les liens de pagination jusqu’à la dernière page. Vérifiez que les liens conservent les options de requête et que le signal d’achèvement documenté est retourné.
• Vérifiez que les champs d’entrée supplémentaires ne peuvent pas modifier les propriétés protégées et que la sélection de champs ne peut pas exposer de données non autorisées.
• Testez les ETags correspondants, non correspondants, faibles, multiples et génériques, et vérifiez que les réponses 304 ne contiennent aucun corps.
• Effectuez des mises à jour simultanées et vérifiez que le magasin de données rejette les écritures obsolètes de façon atomique.
• Vérifiez que les appelants ne peuvent pas lire les ressources d’un autre appelant, les enregistrements d’état ou les réponses mises en cache.
• Pour les API multilocataires, testez les identifiants de locataire falsifiés ou incompatibles. Lorsque la mise en cache est activée, vérifiez les requêtes pour le même URI de ressource provenant de différents locataires.
• Simuler les délais d’expiration, l’annulation du client, les échecs de dépendance, les redémarrages de worker et la remise en double du travail en arrière-plan.
• Vérifiez le délai d’expiration en aval, les budgets de nouvelles tentatives, l’annulation et la récupération du disjoncteur.
• Vérifiez les réponses 429 (Trop de demandes) et 503 (Service indisponible), le comportement de nouvelle tentative et le coût du rejet des demandes surchargées.

Exécutez des tests de charge sur une infrastructure de type production avec des combinaisons d’opérations réalistes. Définissez les critères de réussite et d’échec pour le débit, les centiles de latence, les taux d’erreur et la saturation des ressources. Utilisez Test de charge Azure et intégrez des vérifications de régression dans le pipeline de déploiement.

Utilisation d'API Management

Envisagez d’utiliser Gestion des API Azure lorsque vous avez besoin d’une passerelle managée avec l’application de la stratégie. Il ajoute des coûts, un autre tronçon réseau et une dépendance dans le chemin de la requête. Choisissez un niveau de service et une topologie en fonction de la capacité, de la mise en réseau, de la disponibilité et des exigences régionales ; les fonctionnalités diffèrent par niveau. Le niveau Développeur n’est pas destiné aux charges de travail de production. Suivez les recommandations du service Well-Architected pour API Management.

Vous pouvez publier et gérer une API web en procédant comme suit :

1. Déployez l’API web sur une plateforme d’hébergement telle que Azure App Service, Azure Container Apps, Azure Kubernetes Service (AKS) ou Machines virtuelles Azure.

2. Configurez API Management pour acheminer les requêtes de son URL de passerelle vers l’API back-end. Une instance d’API Management peut acheminer les demandes vers plusieurs API. Plusieurs instances peuvent également exposer la même API back-end lorsque les applications ont besoin de limites d’accès différentes.

   Remarque

   Les liens HATEOAS dans les réponses doivent référencer l’URL de la passerelle API Management, et non l’URL du serveur backend.

3. Importez une définition OpenAPI versionnée et vérifiez que les opérations, paramètres, exigences de sécurité et schémas de réponse importés correspondent à l’implémentation. Vérifiez les versions d’OpenAPI prises en charge et les limitations d’importation. Pour plus d’informations, consultez Importer une spécification OpenAPI.

4. Configurez l’authentification et l’autorisation pour les communications entre le client et la passerelle, et entre la passerelle et le serveur principal. Validez les jetons d’accès OAuth 2.0 et appliquez les autorisations requises pour les requêtes client. Pour les back-ends qui prennent en charge l’authentification Microsoft Entra ID, préférez une identité managée d’API Management avec uniquement les autorisations dont elle a besoin. L’authentification par certificat est une autre option. Évitez l’authentification de base lorsque des options plus sécurisées sont disponibles. Pour plus d’informations, consultez Authentification et autorisation des API dans Gestion des API Azure.

   Remarque

   Si vous avez besoin de clés d’abonnement API Management, ne les utilisez pas comme substitut de l’authentification et de l’autorisation au niveau des ressources.

5. Configurez des stratégies pour l’authentification, l’accès inter-origine, les transformations de message, le filtrage IP, les limites de débit et les quotas en fonction des besoins. Configurez la mise en cache des réponses uniquement pour les données pouvant être mises en cache en toute sécurité. Appliquez des politiques au niveau approprié et vérifiez leur comportement effectif pour chaque opération.

Pour plus d’informations, consultez la documentation Gestion des API.

Prise en charge des développeurs côté client

Fournissez aux consommateurs d’API la documentation relative à l’authentification, aux opérations, aux paramètres, aux types de données et aux codes de réponse.

Documentez les opérations REST associées à une API Web

Publiez une définition OpenAPI qui décrit les opérations, les paramètres, les schémas de requête et de réponse de l’API et les exigences de sécurité. Conservez-la sous contrôle de version avec l’implémentation et vérifiez qu’elle correspond au comportement réel de l’API.

Compléter la référence d’API avec des conseils sur la manière dont les consommateurs doivent utiliser correctement l’API :

• Exigences et autorisations d’authentification pour chaque opération.
• Demandes représentatives, réponses réussies et réponses d’erreur.
• Règles de validation d’entrée, limites de charge utile, pagination et limites de débit.
• Comportement du délai d’expiration, sécurité des nouvelles tentatives et exigences d’idempotence.
• État et récupération des résultats pour les opérations de longue durée.
• Attentes en matière de contrôle de version et de compatibilité.

Conservez la documentation et les exemples à jour lorsque le contrat d’API change.

Implémentez un Kit de développement logiciel (SDK) client

Envisagez de fournir un kit de développement logiciel (SDK) pour les utilisateurs de l’API. Le Kit de développement logiciel (SDK) peut exposer des méthodes typées qui construisent des requêtes, analysent les réponses et exposent les erreurs documentées de l’API.

Envisagez de générer des clients typés à partir de la définition OpenAPI de l’API, mais validez le comportement généré par rapport au service. Documentez l’authentification, les délais d’expiration, l’annulation, la pagination, les réponses d’erreur et les opérations pouvant être relancées sans risque. Veillez à aligner la politique de compatibilité du client et de l’API. Le code généré ne supprime pas la nécessité de tests d’intégration.

Surveillance d’une API Web

Surveillez l’API, ses dépendances et toute passerelle simultanément. Définissez des objectifs et des alertes au niveau du service en fonction de l’impact sur le client plutôt que de vous appuyer uniquement sur l’état de santé de l’hôte.

Surveillance directe d’une API Web

Utilisez l’instrumentation OpenTelemetry pour collecter des traces, des métriques et des journaux, et exporter les signaux vers Application Insights ou un autre back-end pris en charge. Pour .NET, Node.js et l’instrumentation Python, suivez les recommandations de Microsoft OpenTelemetry Distro. Java utilise la distribution OpenTelemetry Azure Monitor. Suivez les instructions d’activation d’OpenTelemetry spécifiques au langage.

Surveillez les signaux qui décrivent le comportement de l’API :

• Volume de requête, taux d’échec et centiles de latence par opération
• Latence des dépendances, échecs et délais d’expiration
• Rejets dus à la limitation de débit, travail simultané et saturation des ressources
• Âge de la file d’attente des opérations en arrière-plan, heure d’achèvement, échecs et nouvelles tentatives
• Efficacité du cache, lorsque la mise en cache fait partie de la conception

Les données de télémétrie qu’un outil de surveillance collecte automatiquement varient en fonction du langage, des bibliothèques et de la configuration. Ajoutez l’instrumentation pour les opérations de domaine et le travail en arrière-plan. Ne supposez pas que les sessions de navigateur, les rôles d’utilisateur ou tous les détails de la demande sont automatiquement disponibles. Propagez le contexte de trace entre la passerelle, l’application et les workers. Configurez l’échantillonnage et la rétention pour équilibrer les besoins de diagnostic, la sensibilité des données et les coûts de télémétrie.

Utilisez les tests de disponibilité Standard d’Application Insights pour les vérifications externes périodiques le cas échéant. Vérifiez un point de terminaison d’intégrité ou d’opération significatif sans exposer de données sensibles, définissez des alertes actionnables et maintenez un runbook de réponse.

Surveillance d’une API web à l’aide d’API Management

Utilisez les métriques Azure Monitor, les journaux, l’analytique et les diagnostics pris en charge par API Management pour distinguer les échecs de passerelle des défaillances back-end. Mettre en corrélation les données de télémétrie de passerelle et d’application et surveiller les échecs de stratégie, la capacité, la latence des requêtes et la limitation. Les signaux disponibles dépendent de la configuration de l’offre et de la passerelle.

Suivez les recommandations en matière d’observabilité et de capacité dans les recommandations du service Well-Architected pour la gestion des API.

Étapes suivantes

• ASP.NET Core vue d’ensemble d’OData explique comment créer des services d’API REST conformes au protocole OData à l’aide de ASP.NET Core.
• Meilleures pratiques ASP.NET Core couvre les E/S asynchrones, l’utilisation des ressources et la gestion des réponses.
• Le modèle de consommateur idempotent fournit des recommandations de mise en œuvre pour le suivi des identifiants de message traités et la gestion des livraisons en double.
• La sémantique HTTP définit les codes d’état HTTP.
• Le modèle Request-Reply asynchrone décrit les tâches d’arrière-plan durables et les ressources d’état associées.
• Les meilleures pratiques d’architecture pour Gestion des API Azure couvrent la fiabilité, la sécurité, le coût, les opérations et les performances.
• Test de charge Azure décrit la génération de charge et les vérifications automatisées des performances.
• L’activation d’OpenTelemetry fournit des instructions d’instrumentation et d’exportation propres à chaque langage.