5 conseils pour une meilleure conception de l’API REST


Il ne fait aucun doute que l ‘”API” est devenue de facto la norme pour l’échange d’informations entre les systèmes et contribue également à une meilleure intégration au sein des composants d’un système.

Dans cet article, je partagerai certaines des pratiques que j’ai suivies tout en travaillant sur la conception et la mise en œuvre de plusieurs API REST.

1. Client SDK au lieu d’écrire notre propre code

Si le fournisseur ou les créateurs de services disposent d’un SDK, je préfère l’utiliser pour les appels d’API au lieu d’écrire ma propre bibliothèque client en plus des appels REST natifs. Un excellent exemple est le kit SDK AWS pour interagir avec Amazon Web Services. Le choix d’utiliser AWS SDK a aidé mon équipe à réduire la courbe d’apprentissage, à commencer immédiatement et à gagner du temps pour écrire la logique à gérer – sécurité, délais d’expiration du réseau, nouvelles tentatives, secours, etc.

Étant donné que ces kits de développement logiciel sont gérés par le fournisseur, les développeurs n’ont pas besoin de se soucier des tests, des correctifs et des modifications pour prendre en charge de nouveaux points de terminaison d’API. La plupart des SDK modernes sont open source et basés sur des protocoles standard (REST, WebSocket, gRPC) supportant des intégrations rapides.

Un inconvénient majeur du SDK API est la disponibilité et la prise en charge des langages de programmation de votre choix. Dans de tels cas, les développeurs doivent développer un client REST personnalisé. Je recommande toujours aux développeurs de le concevoir et de l’implémenter en tant que projet Maven distinct, hébergé dans le référentiel Git d’entreprise, bien documenté et disponible pour toutes les équipes internes de votre organisation.

2. Swagger pour la documentation

Je ne peux pas souligner à quel point le swagger a été bénéfique pour les développeurs d’API et, surtout, pour les personnes qui ne sont pas issues du développement. Il fait également partie de la plupart du cadre de développement moderne pour le rendre facile pour les développeurs. En tant que développeur, je peux facilement exécuter des API et tester au lieu de passer à un autre document et de lire beaucoup de texte. En tant que consommateur de l’API, vous pouvez comprendre l’API, ses paramètres, le modèle de charge utile prévu, etc.

Je ne discrédite pas un document qui peut contenir des informations plus détaillées (y compris un exemple de charge utile), mais j’ai trouvé de nombreux documents de ce type obsolètes par rapport à la version actuelle de l’API. À mon avis, utilisez Swagger pour compléter la documentation et aider les autres développeurs à démarrer rapidement leur intégration.

3. Suivre une approche standard pour les endpoints

Lors de la conception d’une API, de nombreux nouveaux développeurs ne suivent pas une nomenclature standard de points de terminaison ou ne définissent pas les opérations en termes de verbes HTTP. Il existe de nombreuses bonnes ressources disponibles en ligne qui traitent de cette question en détail, voir références.

Peu d’approches que je respecte strictement et que je demande à mes développeurs de suivre:

  1. Ne mélangez pas les majuscules et les minuscules dans les points de terminaison. Par exemple. au lieu de “/ users / userId”, remplacez par “/ users / {id}”. Au lieu de POST “/ deleteUser / userId”, mieux utiliser DELETE “users / {id}”
  2. Utilisez toujours le contrôle de version dans l’URL, par ex. Je suis “/ api / v1 /” comme partie obligatoire de l’URL
  3. Définissez “https” comme option par défaut pour que les clients se connectent.
  4. Avoir un validateur pour la vérification de la charge utile et ce devrait être la première étape du code. Ne le laissez pas pour un traitement ultérieur et comptez sur toutes les exceptions.

4. Gestion des mises à niveau

Imaginez, votre service utilise une API pour publier certaines données, et soudain, cela ne fonctionne pas. Plus tard, après de nombreux e-mails et réunions, vous avez compris que oh! il y a un changement dans la charge utile qui nécessite maintenant un champ obligatoire. Eh bien, la frustration est valable car l’API a été mise à niveau sans compatibilité descendante.

De telles erreurs peuvent également être détectées précocement à l’aide de n’importe quel processus CI, mais en tant que développeur d’API, vous devez penser aux clients existants tout en apportant des modifications aux API, comme pour tout nouveau champ dans le corps de la demande, utiliser une valeur par défaut ou définir une nouvelle version point de terminaison comme “/ api / v2”, etc.

5. Test

Ne vous contentez pas d’un test fonctionnel mais d’un test de charge. Vous devez savoir combien d’appels d’API par minute un serveur peut gérer. Quel est le temps de réponse lorsque la latence du réseau augmente. De nombreux clients d’entreprise ont leurs centres de données répartis dans le monde entier ou utilisent un environnement cloud multi-régions. Il aidera les clients si vous pouvez partager des numéros de référence lorsque vous avez hébergé un serveur API aux États-Unis et en testant des clients à partir d’instances aux États-Unis, en Europe, en Inde et en Australie.

Je préfère utiliser des outils dédiés aux tests d’API tels que Postman ou Apache JMeter au lieu d’en écrire un. Non seulement ils permettent de gagner du temps, mais ils me permettent également d’exporter des modèles que j’enregistre sur git.

Conclusion

Un article ne peut pas couvrir toutes les meilleures pratiques, mais nous espérons que vous devriez avoir une idée des choses. Je crois que le «développement d’API» est comparable à d’autres aspects de l’ingénierie logicielle et à une sorte de domaine spécialisé avec beaucoup de possibilités d’innovation.

Dans l’attente de vos commentaires.

Close Menu