Cependant, l'auteur a rencontré de sérieux problèmes après le lancement effectif du projet :
1. Manque de documentation et de spécifications API complètes :
· La documentation de l'API est incomplète et pleine d'erreurs et ne peut pas être utilisée comme référence précise.
· Il n'existe aucun processus de test d'API convenu, permettant à l'équipe de développement back-end de modifier et de publier l'API à volonté et sans préavis. De tels changements sont souvent des bugs et interrompent l'intégration avec les clients API.
2. Framework et validation API inappropriés :
L'équipe backend a utilisé un framework Flask inapproprié et a mis en œuvre elle-même une validation de charge utile complexe, dont la plupart n'ont pas été testées.
· La partie vérification contient une grande quantité de code, y compris la vérification de la date, de l'horodatage et du format de chaîne, mais elle n'a pas été entièrement testée, ce qui ralentit sérieusement la progression du projet.
Par conséquent , pour résoudre les problèmes ci-dessus , il est nécessaire de réparer et d'améliorer la documentation de l'API pour garantir son exactitude et son exhaustivité ; établir un cadre API approprié pour améliorer la qualité et la testabilité du code et établir des spécifications API strictes pour empêcher la publication de versions qui le font ; ne répond pas aux spécifications.
Corriger la conception et la documentation de l'API
Il ressort des problèmes exposés ci-dessus que l'équipe de développement ne comprend pas les meilleures pratiques de l'API REST et de la spécification OpenAPI. Par conséquent, l'équipe de développement doit d'abord comprendre OpenAPI et son fonctionnement, puis intégrer la documentation de l'API dans la spécification OpenAPI pour avoir une compréhension plus claire du comportement attendu de l'API.
Lors du processus d'intégration de la documentation dans la spécification OpenAPI, nous avons découvert de nombreux problèmes avec les conceptions d'API précédentes. Par exemple, les formats de date personnalisés nécessitaient auparavant une logique de validation personnalisée dans le serveur et l'interface utilisateur. Nous avons résolu ce problème en passant à la norme ISO supportée par OpenAPI pour représenter les dates.
De plus, certains modes sont si flexibles que la validation est quasiment inefficace. Pour améliorer la validation, nous avons refactorisé les schémas et créé un modèle avec des points de terminaison différents pour chaque entité, le rendant plus utilisable.
Les méthodes HTTP et les codes d’état étaient utilisés de manière inappropriée dans la conception précédente. L'équipe utilise uniquement les méthodes GET et POST, et toutes les réponses renvoient un code d'état 200. Cette utilisation inappropriée rend flou la tentative de création, de suppression ou de mise à jour de ressources. Pour résoudre ce problème, nous avons redéfini l'utilisation des méthodes HTTP et renvoyons correctement le code d'état approprié pour indiquer plus précisément le succès ou l'échec de la requête.
Une autre limitation de la conception précédente était la « réutilisation des points finaux ». Bien qu'il semble économiser du code, il expose en réalité trop de détails d'implémentation. Par conséquent, nous devons mettre l’accent sur le concept de conception de l’API d’abord, puis sur la réflexion sur la mise en œuvre.
La fusion de la spécification API avec OpenAPI a été un tournant important pour le projet. Par la suite, nous avons pu exécuter un serveur fictif pour créer et tester l'interface utilisateur avant l'intégration avec le backend, ainsi que vérifier l'implémentation du backend par rapport aux spécifications. Nous utilisons Prism pour exécuter le serveur fictif et Dredd pour vérifier l'implémentation du serveur (même si je préfère utiliser Schemathesis maintenant). Cela permet aux projets de se développer de manière plus claire et plus efficace .
Corriger le processus de publication de l'API
Même s'il existe un document API, s'il n'est pas testé par rapport à la spécification API avant sa publication, le rôle du document deviendra limité. Bien que la documentation elle-même nous aide à comprendre le fonctionnement de l'API, sa véritable puissance réside dans sa fonction d'outil de vérification, vérifiant que le serveur est correctement implémenté.
Pour m'assurer que le serveur API fonctionne comme prévu, j'ai intégré la suite de tests Dredd dans le serveur d'intégration continue. Personne ne peut fusionner et publier un nouveau code à moins qu'il ne passe la validation Dredd et ne soit conforme à la spécification de l'API. Cette étape permet à l'équipe d'éviter des modifications involontaires du serveur API. Désormais, toutes les modifications apportées au serveur doivent être documentées à l'avance et le serveur API doit être assuré de suivre ces modifications avant de fusionner ou de publier. Cette approche garantit la stabilité et la cohérence du serveur.
Choisissez le bon framework de développement d'API
Auparavant, l'équipe avait implémenté le serveur API à l'aide du framework Flask, un framework Python populaire pour la création d'applications Web. Ils ont construit l'API avec Flask de base et ont écrit beaucoup de code personnalisé pour valider la charge utile de l'API. Il s'agit d'une erreur courante commise par de nombreux développeurs d'API inexpérimentés.
Construire une couche de validation d'API personnalisée n'est pas indésirable, mais une dépendance excessive à l'égard de cette approche peut conduire à réinventer la roue. L'API nécessite une logique de validation complexe pour gérer la charge utile et l'URL (paramètres de chemin et de requête), qui doivent être implémentées dans l'ensemble de l'API. Par conséquent, si vous insistez pour créer votre propre couche de vérification d’API, vous finirez par produire un framework API. Cependant, il existe de nombreux excellents frameworks de développement d’API, alors pourquoi ne pas en choisir un ?
Pour Flask en particulier, plusieurs options sont à considérer. Mais tous les frameworks ne sont pas égaux. Par exemple, flasgger, restx (successeur de flask-restplus), flask-RESTful et flask-smorest, etc. Avec autant de choix, comment prendre une décision ?
Lors du choix d'un framework de développement d'API REST, les facteurs suivants doivent être pris en compte :
· Prise en charge d'OpenAPI : le framework doit permettre la création facile d'API REST et générer automatiquement la documentation de l'API, garantissant ainsi l'exactitude de la vérification de la charge utile. Les cadres de référence incluent Flasgger et flask-smorest.
· Validation de données robuste : la validation des charges utiles nécessite une bibliothèque de validation de données robuste pour gérer divers attributs et types. La bibliothèque doit prendre en charge les propriétés facultatives et obligatoires telles que les formats de chaîne (date ISO et UUID), ainsi qu'une validation de type stricte et assouplie. Dans l'écosystème Python, pydantic et marshmallow sont d'excellentes bibliothèques de validation de données, et Flasgger et flask-smorest peuvent utiliser guimauve.
Validation complète : le framework doit prendre en charge la validation des charges utiles de requête, des charges utiles de réponse, des paramètres de chemin d'URL et des paramètres de requête d'URL. Certaines bibliothèques peuvent uniquement valider la charge utile de la demande et ignorer les paramètres d'URL ou la charge utile de la réponse. Assurez-vous que le framework fournit au moins un moyen d'appliquer les règles de validation. Si vous utilisez Marshmallow, la charge utile de réponse peut être vérifiée directement à l'aide de son modèle.
· Maturité : choisissez une bibliothèque mature, stable et bénéficiant du soutien actif de la communauté. Il doit disposer d’une bonne documentation et être capable de résoudre rapidement les problèmes des utilisateurs.
Après avoir évalué les facteurs ci-dessus, nous avons sélectionné flask-smorest, un plug-in Flask qui prend en charge l'utilisation de guimauve pour créer facilement une vérification des données pour les API REST. Cela peut simplifier le processus de vérification des données et réduire la quantité de code personnalisé. Les charges utiles des requêtes et des réponses sont désormais correctement validées, et Marshmallow gère également la validation des requêtes URL et des paramètres de chemin.
Choisir le bon framework API nous permet d’avoir une API fonctionnelle. Étant donné que le framework gère les détails de la couche API, nous pouvons nous concentrer davantage sur la logique métier et le modèle de données de l'application, ce qui entraîne une vitesse de développement accrue et la possibilité de publier plus fréquemment de meilleurs logiciels.
Considérez tout pour créer une excellente API
Dans l'Internet d'aujourd'hui, les API sont omniprésentes et inévitables. Cependant, créer réellement une bonne API est une tâche complexe, tout comme écrire du code lisible et facile à maintenir, créer une interface de haute qualité, facile à utiliser et à modifier est également un défi dans le développement d'API.
Fournir une API de haute qualité est difficile car elle doit être cohérente avec les exigences de l'entreprise, c'est-à-dire que le client et le serveur doivent utiliser les mêmes conventions et spécifications, sinon l'intégration sera difficile à réaliser.
Atteindre cet objectif nécessite de prendre en compte plusieurs aspects : recueillir les exigences des clients, traduire les exigences en détails techniques, concevoir l'API, rédiger la documentation, choisir un framework API approprié et l'utiliser correctement, tester l'API et s'assurer que la mise en œuvre répond aux spécifications de conception. Cela n'inclut pas des aspects tels que la sécurité, le déploiement et le fonctionnement des API.
Lorsqu’il s’agit de créer des API critiques pour l’entreprise, il est conseillé de ne pas laisser cette tâche aux seuls développeurs juniors. Ils peuvent participer, mais un développeur senior est nécessaire pour guider leur travail. Si vous n'avez aucune expérience en développement d'API, suivez la voie des meilleures pratiques : concevez d'abord l'API, puis rédigez la documentation, implémentez-la conformément aux spécifications et vérifiez-la. Ne réinventez pas la roue, choisissez le bon framework !
Même si cela peut prendre un certain temps pour apprendre OpenAPI, comprendre le cadre de test des API, rechercher le cadre de développement d'API, etc., cela en vaut la peine. Sinon, vous resterez coincé dans un cercle vicieux de problèmes d’intégration d’API et de qualité logicielle qui entraveront l’avancement du projet et entraîneront des coûts énormes pour résoudre les problèmes.
Si vous disposez de ressources suffisantes et de développeurs d'API expérimentés, la probabilité de créer correctement l'API sera considérablement augmentée et vous pourrez économiser beaucoup d'argent. En outre, nous devons également prêter attention à la gestion des API. De nombreux problèmes résident non seulement dans les coûts de développement et de dépenses précoces, mais également dans les problèmes de code cachés pendant le processus de développement et dans les transferts peu clairs des employés responsables, ce qui peut entraîner des dangers cachés. Par conséquent, Power Simple Integration estime que la gestion des API peut utiliser des outils tiers pour gérer les API en un seul endroit, avec plusieurs rôles impliqués, afin d'éviter de se soustraire aux responsabilités et d'améliorer l'efficacité du développement.