7 conseils pour créer une bonne API Web

La création d’une bonne API nécessite des précautions supplémentaires. Découvrez dans cet article de blog sept conseils qui vous aideront à créer une bonne API dans ASP.NET Core.

Les bonnes API sont composées de nombreux facteurs, notamment les journaux, la documentation, les performances et autres.

Avec la popularité des API Web, il est extrêmement important que les développeurs aient les connaissances nécessaires pour implémenter de bonnes API. Après tout, ce sera une tâche très courante dans votre routine en tant que développeur Web, en particulier en utilisant les technologies Microsoft telles que ASP.NET Core.

Dans cet article, nous aborderons sept conseils :

1. Ecrire de bons endpoints
2. Utilisez les bons verbes HTTP
3. Évitez de mettre des règles métier sur les points de terminaison
4. Utiliser la pagination et le filtrage
5. Rendre disponible un point de terminaison Health
6. Utiliser l’API de mise en cache
7. Rédiger une bonne documentation

Astuce 1 : écrivez de bons points de terminaison

Utilisez toujours des noms

Lors de la création de points de terminaison, utilisez toujours des noms au lieu de verbes. Voir ci-dessous le mauvais sens et le bon sens.

❌ Faux :
/api/GetOffer/{offer}

✅ Correct :
/api/offers/{offer}

Conventions de nommage

Il existe des différences concernant la nomenclature, mais il est très courant de trouver des URL de géants de la technologie qui utilisent leurs URL toujours en minuscules. Dans le cas où il est nécessaire d’utiliser un mot composé de plus d’un nom, essayez d’utiliser un trait de soulignement (_) ou un tiret (-) pour les séparer. Voir l’exemple suivant :

❌ Faux :
/Api/Orders/AdditionalFields

✅ Correct :
/api/orders/additional_fields
ou alors
/api/orders/additional-fields

Des noms au pluriel ou au singulier ?

Comme vu précédemment, vous devez utiliser des noms au lieu de verbes, mais une question courante est de savoir s’il faut écrire ces noms au pluriel ou au singulier.

Et la réponse est qu’il n’y a pas de forme correcte, c’est à vous de décider. Cependant, je préfère utiliser la forme plurielle car de cette façon, ils indiquent un ensemble de caractéristiques qui peuvent être une ou plusieurs. Lorsque vous utilisez le singulier, vous limitez le point de terminaison à un seul élément, du moins c’est l’impression que cela donne.

Quelle que soit la façon dont vous l’utilisez, le but est toujours de simplifier les choses.

👌 Bon (singulier):
/api/order/additional_field

🚀 Mieux (pluriel):
/api/orders/additional_fields

Versions

Il est très courant que les API évoluent après leur première version, il est donc important de créer différentes versions de la même API. De nombreuses entreprises choisissent de le rendre explicite dans les points de terminaison qui est la version de l’API via la lettre « v » + le numéro de version. Donc, normalement dans la première version, nous voyons « v1 ».

Les API de gestion des versions peuvent aider à la maintenance du système. Les systèmes qui utilisent le point de terminaison v1 ne sont pas affectés, car toutes les modifications sont rendues disponibles sur un autre point de terminaison, dans ce cas, la v2.

Mais il est important de préciser que ce n’est pas obligatoire. De nombreuses entreprises ne créent généralement pas de versions pour leurs API. Dans ces cas, de nouvelles API sont créées et remplacent les anciennes.

👌 Bon :
Point de terminaison non versionné : api/offers/{offer}

🚀 Mieux :
Point de terminaison versionné : api/v1/offers/{offer}

Astuce 2 : Utilisez les bons verbes HTTP

Tout d’abord, vous devez apprendre les bases de HTTP. Ce n’est pas un sujet compliqué, alors nous mettons souvent de côté la documentation et allons à la pratique, ce qui entraîne une mauvaise utilisation des ressources disponibles dans cette technologie. Une excellente référence pour comprendre les concepts HTTP est cette page créée par Mozilla Firefox : Bases de HTTP.

Voici les principaux verbes HTTP et leurs fonctions respectives :

Utilisez les bons codes d’état HTTP

Une fonctionnalité précieuse disponible dans HTTP est le statut. Ces statuts sont renvoyés dans la réponse du serveur, en fonction du résultat de l’action envoyée dans la requête, qui peut être un succès ou un échec. Quel que soit le résultat, il existe plusieurs types de statuts, c’est au développeur d’implémenter le statut correct en fonction de la situation.

Par exemple, une API reçoit via une chaîne de requête l’identifiant du vendeur. Si l’identifiant existe dans la base de données, l’API renvoie les données du vendeur correspondant. Sinon, l’API renvoie une erreur avec une description détaillée. Ci-dessous les deux scénarios :

1. Vendeur trouvé

HTTP/1.1 200 OK
Content-Type: text/html

{
    "status": "success",
    "data": 
    {
        {
            "idSeller": "100002132",
            "name": "SellerExample",
            "offerCode": "4",
            "smallSeller": false
        }
    }
}

2. Vendeur introuvable

HTTP/1.1 404 Not Found
Content-Type: text/html

{
    "status": "error",
    "messages": [
        {
            "code": "018",
            "message": "Seller not found"
        }
    ]
}

Un autre point important est l’utilisation cohérente du statut de retour. Par exemple, en cas de succès, pour chaque verbe, il existe un modèle couramment utilisé.

• OBTENEZ : 200 OK
• POSTE : 201 créé
• MET: 200 OK
• SUPPRIMER : 204 Aucun contenu
• PATCH : 200 OK

Vous pouvez consulter la liste complète des statuts disponibles dans la documentation de Mozilla Firefox : Codes d’état HTTP.

Astuce 3 : évitez de mettre des règles métier sur les points de terminaison

Les points de terminaison d’une API sont utilisés pour l’entrée et la sortie des données, donc la meilleure option est de créer une classe, communément appelée Service, d’y mettre les règles métier, puis d’appeler simplement la méthode principale de la classe de service sur les points de terminaison. . Comme vous pouvez le voir dans les exemples ci-dessous :

❌ Faux :

app.MapPost("v1/products", (Product product, ProductDbContext dbContext) =>
{
    string errorMessage = string.Empty;

    if (string.IsNullOrEmpty(product.Name))
        errorMessage += "Name is mandatory";

    if (string.IsNullOrEmpty(product.Category))
        errorMessage += "Category is mandatory";

    if (!string.IsNullOrEmpty(product.Name))
        Results.BadRequest("Error creating the product");

    else
    {
        dbContext.Products.Add(product);
        dbContext.SaveChanges();
        return Results.Ok();
    }

}).WithName("CreateProduct");

✅ Correct :

app.MapPost("v1/products", (ProductService service, Product product) =>
{
    var resultMessage = service.Create(product);

    if (string.IsNullOrEmpty(resultMessage))
        Results.BadRequest($"Error creating the product, error validation: {resultMessage}");

    return Results.Ok();

}).WithName("CreateProduct");

Astuce 4 : Utilisez la pagination et le filtrage

Il est très courant que les applications se développent au fil du temps, et il est important de permettre aux consommateurs d’API d’avoir la possibilité d’obtenir uniquement une certaine quantité d’éléments selon leurs besoins. Une suggestion pour cela est la pagination.

Pour implémenter la pagination sans exiger beaucoup de performances de la part de la base de données, le meilleur moyen est de fournir un paramètre (identifiant) qui peut « couper » une collection d’enregistrements et un limiteur de quantité.

Vous pouvez voir un mauvais et un bon exemple ci-dessous. Dans le premier exemple, il n’y a pas d’options ou de limitations de pagination. Dans le second, il est possible de remarquer ces paramètres présents dans la route endpoint.

👌 Bon :
GET v1/produits

🚀 Mieux :
OBTENIR v1/products?limit=100&category=casque

Astuce 5 : Rendre un point de terminaison de santé disponible

Il est de bonne pratique de mettre à disposition de tous les consommateurs une route Health, qui sert, comme son nom l’indique, à vérifier la santé d’une API. Dans ce cas, non seulement si l’API est disponible, mais vous pouvez vérifier les dépendances de l’API et renvoyer le résultat obtenu dans chacune d’elles.

Par exemple, dans une API qui doit générer un jeton dans une API externe, vous pouvez vérifier dans le point de terminaison Health si cette API externe est disponible et renvoyer le résultat de la vérification dans la route Health.

Ainsi, il est possible pour les consommateurs de savoir rapidement où peut être la cause du problème, dans le cas où leur API renvoie une erreur 500 (erreur interne du serveur). Vous trouverez ci-dessous un exemple de point de terminaison Health.

GET – v1/produits/santé

app.MapGet("v1/products/health", (ProductService service) =>
{
    var externalAPIResponse = service.ExternalAPIHealthVerify();
    return Results.Ok($"External API response: {externalAPIResponse.StatusCode} - {externalAPIResponse.Message}");

}).WithName("Health");

Astuce 6 : Utilisez la mise en cache de l’API

Le cache est une technique utilisée pour stocker des données fréquemment utilisées. Il est très utile car il vise à gagner en performance et à réduire la charge sur les services Web/base de données en stockant les données dans un endroit facile d’accès, qui peut être le cache en mémoire (mémoire du serveur), le cache persistant en cours (fichier ou base de données) ou cache distribué (plusieurs processus).

Ci-dessous, vous pouvez voir un exemple d’implémentation de la mise en cache de la mémoire dans une API Web ASP.NET Core.

app.MapGet ("v1/products", (ProductService service) =>
{
    const string ProductsKey = "_Products";

    if (!cache.TryGetValue(ProductsKey, out List<Product> products))
    {
        products = service.GetAll();
        var cacheEntryOptions = new MemoryCacheEntryOptions
        {
            AbsoluteExpiration = DateTime.Now.AddMinutes(3),
            SlidingExpiration = TimeSpan.FromMinutes(2),
            Size = 1024,
        };
        cache.Set(ProductsKey, products, cacheEntryOptions);
    }
    return Results.Ok(products);

}).WithName("GetProducts");

Astuce 7 : Rédigez une bonne documentation

La rédaction d’une bonne documentation est essentielle au développement d’une API. Après tout, c’est par le biais de la documentation que les développeurs implémenteront les consommateurs de cette API.

Les grandes entreprises ont utilisé un modèle très similaire les unes aux autres pour fournir de la documentation sur leurs API. Il s’agit généralement d’une page Web très simple qui contient toutes les informations nécessaires à la création d’un consommateur à partir de zéro.

Voici quelques exigences pour une bonne documentation.

• Faites une brève description des fonctions de l’API. Ajoutez toujours des détails importants sur toute règle métier. Exemple : « Pour annuler un achat, vous devrez attendre 24 heures après avoir passé la commande… »
• Séparez toujours la demande de la réponse. Pour chacun d’eux, indiquez le verbe HTTP et la route à laquelle accéder, laissez également un exemple des données à envoyer dans la requête et à renvoyer dans la réponse.
• Si l’API contient une certaine complexité, fournissez toujours un organigramme de processus. Il est plus intuitif d’utiliser des images pour décrire un processus que de le décrire avec des mots.

Conclusion

Une bonne API est composée de plusieurs facteurs, qui réunis apportent plusieurs avantages tels qu’une intégration facile, un développement rapide, une maintenance facile, etc.

Dans cet article, nous avons abordé sept sujets avec des conseils pour créer des API Web professionnelles et de qualité. Ainsi, lors de la création d’une nouvelle API, assurez-vous de n’en oublier aucune.