Réflexions sur la conception de services
Cet article est principalement une note de lecture, extrait de la partie importante de l'auteur du billet de blog dans l'article. Lien d'origine
Introduction
Afin d'éviter que l'API conçue ne sème la confusion chez les utilisateurs, les trois principes suivants doivent être respectés :
- Mettre en œuvre la gestion des versions de l'API à partir de la première version publiée du service
- Assurez-vous que les charges de travail des clients ne sont pas interrompues
- Assurez-vous que les clients n'ont pas besoin de modifier le code d'origine lors de la mise en œuvre de nouveaux services ou de l'intégration du SDK
Commencez avec l'expérience de développeur
Une bonne API commence généralement par un service bien pensé et bien conçu. Votre service doit être défini comme une série de noms de concepts faciles à comprendre, tant que vous mentionnez vos noms de concepts, vous pouvez penser à votre service. Il doit y avoir une relation claire entre ces concepts abstraits.
Afin que vous puissiez créer un ensemble de noms clairs et compréhensibles pour les concepts de votre service, vous devez suivre ces pratiques :
- N'inventez pas de concepts fantaisistes ou n'utilisez pas de mots fantaisistes. Expliquez les concepts de votre service à des non-experts dans le domaine, puis utilisez des termes similaires pour nommer ces concepts.
- N'utilisez pas de mots jetables dans des noms tels que "réponse", "objet", "charge".
- Évitez les noms génériques, les noms doivent être spécifiques à une abstraction, le nom peut souligner sa différence par rapport aux autres abstractions de service.
- Choisissez un mot parmi un ensemble de synonymes et utilisez-le de manière cohérente.
Il est extrêmement difficile de créer une API élégante en plus d'un service mal conçu, et l'équipe de service et les clients supporteront cette douleur pendant des années. L'équipe de service doit donc suivre les principes suivants pour répondre aux besoins des clients :
- Créer des applications qui utilisent l'API
- Continuez à réviser et partagez ce que vous apprenez avec votre équipe
- Obtenir les commentaires des clients sur l'aperçu de l'API
- Pensez au code que les clients doivent écrire avant et après les opérations HTTP
- Initialisez et lisez les structures de données dont votre service a besoin
- Réfléchissez aux bogues qui peuvent être corrigés au moment de l'exécution, plutôt que d'indiquer les bogues dans le code du client qui doivent être corrigés.
Le but de l'aperçu est de résoudre une série de problèmes tels que l'abstraction, la dénomination, la relation et le fonctionnement de l'API des résultats de rétroaction. Des améliorations significatives peuvent être apportées lors de l'aperçu pour améliorer l'expérience aujourd'hui et la rendre durable à long terme.
Focus sur les scénarios de héros
Tout d'abord, il convient de suivre le principe suivant : c'est-à-dire qu'il faut fournir le moins de fonctions possible et, au fil du temps, de nouvelles fonctions doivent être fournies lorsque les clients ont des besoins.
Se concentrer sur les scénarios de héros réduit les coûts de développement, de support et de maintenance. Permet aux équipes de s'aligner et d'atteindre un consensus plus rapidement, ce qui se traduit par des délais de livraison plus rapides.
Pour les Scénarios Héros, à rencontrer :
- Vous devez d'abord définir les scénarios de héros, y compris l'abstraction, la dénomination et la relation, puis définir l'API requise pour le fonctionnement
- Fournit un exemple de code pour illustrer les scénarios de héros
- Réfléchissez à la façon dont vos abstractions seront représentées par différents langages de haut niveau
- Utilisez au moins un langage dynamique (python, js) pour développer un exemple de code et un langage statique (java, C#) pour illustrer vos représentations de langage abstraites et de haut niveau
- N'ajoutez pas de fonctionnalités à l'API dont les utilisateurs sont susceptibles d'avoir besoin
Commencez par définir l'API
Comprenez comment votre service est utilisé et quels sont ses modèles d'interaction :
vous pouvez utiliser OpenAPI pour décrire les services.
Itérer avec aperçu
Obtenez les commentaires des utilisateurs et parcourez plusieurs versions d'aperçu avant de publier une version de votre API qui a nécessité un énorme travail de conception. Ceci est particulièrement important pour les API v1, car cela établit directement les abstractions et les modèles d'interaction des développeurs avec votre service.
vous devez:
- Rédigez et testez des hypothèses sur la façon dont vos clients utiliseront l'API
- Publier et évaluer au moins deux versions d'aperçu avant la première version GA
- Identifiez les scénarios clés et les décisions de conception dans l'API que vos clients testent ensemble, et demandez aux clients de fournir des commentaires et de partager des exemples de code pertinents.
- Vous pouvez envisager des exercices de développement de code, développer avec les clients, observer et apprendre de leur utilisation de l'API.
- Vous devez résumer les connaissances que vous avez acquises lors de la phase de prévisualisation et les partager avec votre équipe et l'équipe de gestion des API.