Nouvelles

Jul 04, 2023

Les revues de conception d'API sont mortes. Longue vie aux critiques de conception d'API !

Accueil InfoQ Articles API Design

Accueil InfoQ Articles Les revues de conception d'API sont mortes. Longue vie aux critiques de conception d'API !

22 mai 2023 8 minutes de lecture

par

Jason Harmon

revu par

Thomas Betts

Lors de la conception d'API à grande échelle, il faut un effort délibéré pour créer de la cohérence. La principale différence entre un ensemble d'API et quelque chose qui ressemble à une véritable plate-forme est la cohérence. Dans ce cas, la cohérence signifie simplement que si vous utilisez plusieurs API, des facteurs tels que les conventions de dénomination, les modèles d'interaction tels que la pagination et les mécanismes d'authentification sont standard dans tous les domaines.

Traditionnellement, les comités de révision ont traumatisé les développeurs d'API avec des découvertes retardatrices lorsque le développement est considéré comme terminé. Pire encore, la conception par un comité peut prendre le dessus, bloquer les progrès ou encourager les développeurs à trouver des moyens de contourner le processus pour éviter complètement la douleur.

Pour vraiment déverrouiller une plate-forme moderne, l'activation par le biais d'une gouvernance décentralisée est une approche beaucoup plus évolutive et engageante. Cela signifie simplement que chaque domaine ou domaine fonctionnel a un expert en la matière qui a été formé aux normes et à l'architecture globale pour être un guide bien adapté aux développeurs d'API.

Protéger les identités. Services numériques sécurisés. Activez un accès utilisateur évolutif et sécurisé aux applications Web et mobiles. Commencer l'essai gratuit.

Plus important encore, s'entendre sur la conception de l'API avant que la majeure partie du développement ne soit terminée peut largement éviter les découvertes de dernière minute qui compromettent les délais de livraison (souvent appelée approche axée sur la conception). L'utilisation d'un format de spécification comme OpenAPI (la norme de facto pour les API HTTP/"REST") offre la possibilité de définir une API avant tout développement, ce qui permet un alignement et une identification des problèmes beaucoup plus précoces.

Dans ce contexte, examinons de plus près comment effectuer des revues de conception d'API, et comment développer des processus et préparer l'organisation pour éviter des délais prolongés et un manque d'engagement des développeurs.

Voici quelques conditions préalables clés pour assurer un processus fluide :

L'utilisation des API est une expérience très distillée, et en tant que telle, l'impact du langage est disproportionnellement plus élevé que la plupart des autres domaines de conception. Chaque membre de l'équipe peut avoir une manière légèrement différente de définir et de décrire divers termes, ce qui se traduit par une confusion et une baisse de productivité pour les équipes API.

Bien que les portails/la documentation d'API soient essentiels à une excellente expérience de développement, des API bien conçues devraient raconter l'essentiel de l'histoire sans avoir à y penser beaucoup. Si les termes sont familiers au consommateur et que les modèles d'interaction sont évidents, l'expérience peut être rapide et indolore. La cohérence est la principale différence d'expérience entre un ensemble d'API et quelque chose qui ressemble à une plate-forme.

Lors de l'établissement de votre programme d'API et de votre processus de gouvernance, commencez par un langage partagé. Bien que cela puisse sembler impossible au premier abord, définir un vocabulaire/grammaire partagé centré sur le client pour votre plateforme est essentiel, et un accélérateur global pour une organisation. De nombreux termes peuvent avoir des significations variées au sein d'une entreprise, et pour aggraver les choses, ce sont souvent des termes que les consommateurs finaux ne reconnaîtraient même pas.

Faire ces devoirs dès le départ évite les conflits de nommage au milieu de la conception des API. Travaillez dans chaque domaine avec les parties prenantes concernées pour définir une terminologie partagée et assurer une large disponibilité et sensibilisation aux concepteurs d'API. Et une fois que vous avez choisi la normalisation interne des termes, n'oubliez pas de vérifier si elle correspond également à vos besoins externes. L'utilisation du langage client et une vision centrée sur le client du développement d'API aident les équipes à éviter de confondre leurs clients avec des termes techniques inconnus, alors assurez-vous qu'il y a une synchronisation entre votre compréhension interne et votre compréhension externe.

Lorsque les consommateurs d'API rencontrent des modèles ou des paramètres qui varient d'une API à l'autre, cela peut être un processus déroutant, frustrant et chronophage. Par exemple, si vous utilisez une API qui fait référence aux informations de contact et que l'API suivante de la même plate-forme utilise un modèle complètement différent, les consommateurs doivent souvent résoudre ces différences. Pire encore, des différences systémiques dans le traitement de ces données peuvent se déployer, créant des différences fonctionnelles.

Dès que possible, identifiez les composants communs (modèles, paramètres, en-têtes, etc.) et les systèmes qui les prennent en charge. La liaison aux composants partagés dans les définitions d'API garantit que les modifications futures de ces composants sont plus faciles à déployer sur la plate-forme, tout en réduisant la charge cognitive excessive des consommateurs d'API.

Plus vous avez de composants communs, meilleures sont les chances d'accroître la cohérence, la réutilisabilité, d'autres opportunités de collaboration et d'améliorer l'efficacité. Dans le monde des développeurs, nous aimons tous la "méthode DRY" (Ne vous répétez pas), et plus il y a de composants partagés, plus il est facile d'innover sans avoir à refaire la même chose à partir de zéro encore et encore. Les composants partagés permettent également à votre équipe d'évoluer rapidement, en formant facilement de nouveaux développeurs ou parties prenantes en dehors de l'équipe API.

Pour la grande majorité des conventions de dénomination simples, des modèles d'interaction et des mécanismes d'authentification, une automatisation avec des guides de style peut être fournie pour signaler les incohérences le plus tôt possible.

Les premiers guides de style ont été développés entre 2013 et 2015, définissant les attentes en matière d'apparence (alias DX) pour les équipes de développement d'API. Le besoin de cohérence de conception était évident dès le début du développement de la plate-forme API, et les premiers efforts de Paypal (je faisais partie de cette équipe à l'époque en fait !) et Heroku ont abouti à certains des premiers guides de style de programmes réussis à être partagé publiquement.

Bien qu'il existe une variété d'outils d'automatisation disponibles pour aider avec les guides de style, l'outil open source Spectral est devenu une norme pour définir les ensembles de règles de linting API. L'alignement initial sur les conventions pour les chemins, les paramètres, etc., et la définition de règles de linting automatisées éviteront les retards dus aux conflits sur les conventions "correctes". Ayez la discussion une fois, et définissez des règles... essayez de ne plus en reparler ; faites simplement disparaître les erreurs de peluches !

Pour les normes de conception qui ne peuvent pas être automatisées, celles-ci doivent être documentées et facilement accessibles aux concepteurs d'API. Une formation qui explique l'importance des règles automatisées et vérifiées manuellement peut motiver les développeurs à soutenir pleinement l'initiative et éviter les surprises et les frictions.

Alors qu'une équipe d'activation d'API doit exister pour organiser ces normes de conception et favoriser la communauté, l'autorité doit être activée dans chaque domaine ou domaine fonctionnel.

Bien que les normes API soient importantes, la connaissance du domaine des contraintes systémiques, des besoins spécifiques des clients et des forces et faiblesses organisationnelles est mieux gérée par un expert qui fait partie de ce monde. Si les membres de l'équipe centralisée d'activation de l'API sont censés être au courant de tout dans l'entreprise, les goulots d'étranglement entraînant des retards de livraison et le désengagement des développeurs sont presque garantis.

Les ateliers de formation peuvent être une technique puissante pour faire prendre conscience de l'importance des normes API. De plus, vous découvrirez souvent les bonnes PME pour fournir l'autorité de gouvernance. Recherchez des personnes qui expriment une passion pour les API (je les appelle souvent une "bande de rebelles"), qui sont conscientes de la pertinence de la cohérence et des normes et qui ont le respect technique de leurs pairs et/ou de leurs rapports.

Le développement d'une API réussie impliquera de nombreuses personnes au sein de votre organisation, souvent avec des compétences contrastées, certaines qui construiront et déploieront l'API, et d'autres qui seront du côté stratégique du problème commercial identifiant la valeur de votre API. N'oubliez pas non plus les parties prenantes de l'entreprise lorsqu'il s'agit de savoir qui impliquer dans la revue de conception. Souvent, nous n'incluons que l'aspect technique, ce qui peut entraîner un échec par la suite. Plus il y a de perspectives, mieux c'est !

Votre plateforme doit avoir des chefs de produit qui s'accordent sur la composition globale du portefeuille/catalogue d'API. Les catalogues se présentent sous de nombreuses formes différentes et organisent vos API pour faciliter la recherche de ce dont vous avez besoin sans avoir besoin de savoir exactement ce que vous recherchez. Il permet aux utilisateurs potentiels de parcourir les API disponibles regroupées par fonctionnalité ou autres préoccupations des utilisateurs.

Les bons catalogues sont consultables ou filtrables afin que les développeurs puissent facilement affiner les options, et ils offrent des détails comparables et digestes pour chaque API du catalogue qui offrent une voie claire vers l'avant.

Pour toute nouvelle API proposée, un aperçu fonctionnel avec des cas d'utilisation et une dénomination de base doit être examiné le plus tôt possible. Cela garantit l'alignement du langage, la réutilisabilité et l'"adéquation" globale d'une nouvelle API par rapport à la perspective de la plate-forme plus large.

Votre équipe d'activation doit avoir des chefs de produit qui sont responsables du processus d'alignement du portefeuille, et chacun doit posséder une collection gérable de domaines. À tout le moins, un lieu régulier permettant aux PM spécifiques à un domaine d'avoir des discussions d'alignement est essentiel.

Bien que cela puisse sembler beaucoup, rappelez-vous que les normes API doivent évoluer par itération. Au fur et à mesure que chaque API est conçue, vous reconnaîtrez les opportunités d'affiner les normes. Dans cet esprit, assurez-vous que les bases sont couvertes dans vos devoirs initiaux et assurez-vous que les gouverneurs de l'API ont une compréhension claire de la façon de proposer et d'adopter des modifications aux normes.

Si vous avez rempli les conditions préalables ci-dessus, il n'y a pas grand-chose à faire dans l'examen de la conception de l'API ! Si des PME centrées sur le domaine sont impliquées, l'examen de la conception peut souvent être largement intégré aux efforts de conception en cours. Si "l'adéquation" à la plate-forme est alignée tôt, les réviseurs de conception doivent avoir la certitude que cette API appartient à l'image plus grande. De plus, si les concepteurs d'API voient des erreurs de peluche lors de l'itération, il ne devrait y avoir aucune discussion sur les conventions de base au-delà de la formation des développeurs sur la pertinence des diverses règles de peluche ou simplement sur la façon de résoudre les erreurs de peluche.

Tout ne peut pas être automatisé, et parfois les besoins du produit et de l'architecture peuvent entrer en conflit. Faites de votre révision de conception d'API un moment où les conventions appliquées manuellement sont vérifiées, la langue du client est validée (car cela est difficile à automatiser) et l'alignement final est solidifié. Avec cette portée à l'esprit, les réunions peuvent souvent être contournées et les discussions asynchrones peuvent souvent suffire.

Plus important encore, gardez un œil attentif sur le temps de cycle d'examen de la conception des API... il devrait diminuer nettement au fil du temps, à mesure que les PME plus décentralisées se familiarisent avec les normes existantes et comment adopter de nouvelles normes.

Écrire pour InfoQ a ouvert de nombreuses portes et augmenté les opportunités de carrière pour moi. J'ai pu m'engager profondément avec des experts et des leaders d'opinion pour en savoir plus sur les sujets que j'ai abordés. Et je peux également diffuser mes apprentissages à la communauté technologique au sens large et comprendre comment les technologies sont utilisées dans le monde réel.

J'ai découvert le programme de contributeur d'InfoQ plus tôt cette année et je l'apprécie depuis ! En plus de me fournir une plate-forme pour partager l'apprentissage avec une communauté mondiale de développeurs de logiciels, le système d'évaluation par les pairs d'InfoQ a considérablement amélioré mon écriture . Si vous cherchez un endroit pour partager votre expertise logicielle, commencez à contribuer à InfoQ.

J'ai commencé à écrire des nouvelles pour la file d'attente InfoQ .NET afin de me tenir au courant de la technologie, mais j'en ai retiré tellement plus. J'ai rencontré des gens compétents, obtenu une visibilité mondiale et amélioré mes compétences en écriture.

Devenir éditeur pour InfoQ a été l'une des meilleures décisions de ma carrière . Cela m'a mis au défi et m'a aidé à grandir de tant de façons . Nous aimerions avoir plus de monderejoins notre équipe.

InfoQ recherche un rédacteur en chef à temps plein pour rejoindre l'équipe internationale et toujours distante de C4Media. Rejoignez-nous pour couvrir les technologies les plus innovantes de notre époque, collaborer avec les praticiens du logiciel les plus brillants au monde et aider plus de 1,6 million d'équipes de développement à adopter de nouvelles technologies et pratiques qui repoussent les limites de ce que les logiciels et les équipes peuvent offrir !

Un résumé du contenu de la semaine dernière sur InfoQ envoyé tous les mardis. Rejoignez une communauté de plus de 250 000 développeurs seniors. Voir un exemple

Nous protégeons votre vie privée.

Vous devez enregistrer un compte InfoQ ou vous connecter ou vous connecter pour publier des commentaires. Mais il y a tellement plus derrière l'inscription.

Tirez le meilleur parti de l'expérience InfoQ.

HTML autorisé : a,b,br,blockquote,i,li,pre,u,ul,p

HTML autorisé : a,b,br,blockquote,i,li,pre,u,ul,p

HTML autorisé : a,b,br,blockquote,i,li,pre,u,ul,p