Les révisions de conception d’API sont mortes. Vive les revues de conception d’API !

Jul 28, 2023

Articles sur la page d'accueil InfoQ Les critiques de conception d'API sont mortes. Vive les revues de conception d’API !

22 mai 2023 8 min de lecture

par

Jason Harmon

revu par

Thomas Betts

Lors de la conception d’API à grande échelle, des efforts délibérés sont nécessaires pour créer une cohérence. La principale différence entre un ensemble d’API et quelque chose qui ressemble à une véritable plateforme 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 d'examen traumatisent les développeurs d'API avec des découvertes qui entraînent des retards alors que le développement est considéré comme terminé. Pire encore, la conception en comité peut prendre le relais, freinant les progrès ou encourageant les développeurs à trouver des moyens de contourner le processus pour éviter complètement les difficultés.

Pour véritablement débloquer une plateforme moderne, l’habilitation via une gouvernance décentralisée est une approche beaucoup plus évolutive et engageante. Cela signifie simplement que chaque domaine ou domaine fonctionnel dispose d'un expert en la matière qui a été formé aux normes et à l'architecture globale pour constituer un guide efficace pour les développeurs d'API.

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

Plus important encore, se mettre d’accord sur la conception de l’API avant que l’essentiel du développement ne soit terminé peut largement éviter les découvertes de dernière minute qui mettent en péril 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 beaucoup plus précoces des problèmes.

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

Voici quelques conditions préalables clés pour garantir le bon déroulement du processus :

L’utilisation des API est une expérience très distillée et, en tant que telle, l’impact du langage est disproportionné par rapport à 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 manifeste par une confusion et une diminution de la productivité pour les équipes API.

Bien que les portails et la documentation API soient essentiels à une expérience de développement exceptionnelle, des API bien conçues devraient raconter l'essentiel de l'histoire sans avoir à y réfléchir beaucoup. Si les termes sont familiers au consommateur et que les modèles d’interaction sont évidents, l’expérience peut alors ê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 seule plate-forme.

Lors de l'établissement de votre programme API et de votre processus de gouvernance, commencez par un langage partagé. Même si cela peut sembler impossible au premier abord, définir un vocabulaire/grammaire partagé centré sur le client pour votre plateforme est essentiel et constitue 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 dénomination lors de la conception des API. Travaillez sur chaque domaine avec les parties prenantes concernées pour définir une terminologie commune et assurez une large disponibilité et sensibilisation des concepteurs d'API. Et une fois que vous avez opté pour une standardisation interne des termes, n'oubliez pas de vérifier si cela 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. Assurez-vous donc qu'il y a une synchronisation entre votre compréhension interne et votre compréhension externe.