Approche Design-First Du Développement D'API : Comment L'implémenter Et Pourquoi Cela Fonctionne

Pensons un instant aux plus grands chefs-d'œuvre du monde.

« Hamlet » de Shakespeare. "Mona Lisa" de De Vinci. La beauté architecturale de Frank Lloyd Wright qu'est "Fallingwater". Le concerto "Quatre Saisons" de Vivaldi. Je pourrais continuer encore et encore, et si cela ne tenait qu'à moi, j'inclurais également le meilleur pick-up au monde jamais créé. Mais, je m'égare.

Tous ces chefs-d'œuvre ont une chose en commun : ils ont été construits en pensant d'abord au design. Vous ne pouvez pas construire une maison sans un plan, et vous pouvez parier que De Vinci ne s'est pas contenté de le piloter sur la "Mona Lisa".

Commencer par une conception n'est pas une idée nouvelle, et les plus grands créateurs du monde l'ont pratiquée au fil des générations, mais avoir une approche "design-first" des interfaces de programmation d'application (API) l'est.

Hein ? Vous pouvez vous demander. Laisse-moi expliquer!

Grâce à l'explosion de l'économie numérique, il y a actuellement 27 millions de développeurs de logiciels dans le monde, et ce nombre devrait bien dépasser 45 millions d'ici 2030. Aujourd'hui, 19 millions de ces développeurs sont des développeurs d'API, et la taille du marché des logiciels de développement d'applications devrait augmenter de 196 % d'ici 2027. Maintenant, je ne sais pas pour vous, mais je considérerais cela comme un marché important.

Avec cette croissance rapide de l'industrie des API, il s'ensuit que davantage de développeurs et de leaders technologiques ont besoin de savoir comment réussir ces efforts. De plus en plus, les personnes occupant ces rôles essentiels doivent comprendre ce qu'il faut pour créer un programme d'API solide, performant et évolutif qui générera de la valeur métier.

Par où commencer ? Quels sont les facteurs les plus importants à considérer ?

Il y a bien sûr de la complexité, mais je suis ici pour vous dire que le facteur le plus important à prendre en compte est de commencer par une approche design-first de votre stratégie d'API. En tant que développeurs, nous pouvons avoir le prochain chef-d'œuvre de l'API à portée de main ; nous devons juste le concevoir d'abord.

Les approches de votre stratégie d'API

D'accord, vous avez donc une excellente idée d'API qui profitera à l'entreprise, mais et ensuite ?

Vous pouvez commencer par rédiger les exigences métier de l'API, puis procéder à son codage. Ou peut-être décidez-vous d'abord de décrire votre API dans un langage de spécification, tel que OpenAPI. Vous pourriez même convaincre votre organisation de prendre votre idée et de la transformer en un produit API-first. Lequel est-ce ?

Passons en revue les approches les plus courantes - Code-First, API-First ou Design-First - et passons en revue les avantages et les inconvénients de chacune :

• Code-First : lorsqu'un développeur doit déployer rapidement une API, passer directement au codage après avoir reçu les exigences métier accélérera le déploiement de l'API. Parfois, c'est l'option la plus rapide si l'API n'a que quelques endpoints. En un mot, Code-first est entièrement orienté vers les développeurs et ne se soucie pas des autres utilisateurs potentiels de l'API.

Le problème avec une approche code-first est que même les API bien conçues développées de cette manière sont prédestinées à l'échec car le succès d'une API repose sur son adoption et son utilisation par de plus en plus d'utilisateurs. Au fur et à mesure que l'adoption augmente, la plupart de vos nouveaux utilisateurs ne seront pas des développeurs ou des personnes à l'esprit technique : ce seront simplement des personnes essayant de résoudre les problèmes aussi rapidement et efficacement que possible. Si une API n'est pas intuitive et applicable à son contexte, une personne lambda ne l'utilisera tout simplement pas.

• API-First : il s'agit d'une approche de plus en plus promue. Fondamentalement, cela signifie que votre organisation traite les API comme l'élément central, étant entendu qu'il s'agit d'actifs métier essentiels sur lesquels l'organisation opère. Ce processus est initié avec un contrat rédigé dans un langage de description d'API tel qu'OpenAPI. Il n'y a rien de mal à cela, et il est sage de standardiser tôt sur une plate-forme ou un ensemble de produits. Le problème est que la langue choisie et ses particularités dominent souvent et même limitent la capacité d'une entreprise à évoluer et à construire pour l'avenir. Si votre API est la chose la plus importante, qu'est-ce que cela dit de toutes les personnes qui la développent et/ou l'utilisent ?


• Design-First : cette approche signifie fondamentalement que tout effort d'API, qu'il s'agisse d'une ou de plusieurs dans un programme, commence par un processus de conception. Dans ce modèle, les API sont définies de manière itérative que les humains et les ordinateurs peuvent comprendre, avant même qu'aucun code ne soit écrit. L'objectif est que chaque équipe parle le même langage et que chaque outil utilisé exploite la même conception d'API. La différence cruciale ici par rapport à une approche API-first est que, bien que l'API soit extrêmement importante, le processus de conception est ce qui garantit que toutes les parties prenantes sont impliquées et que leurs besoins sont satisfaits lors de la création.

Design-First commence avec des individus techniques et non techniques de chacune des fonctions impliquées participant au processus de rédaction d'un contrat qui définit l'objectif et la fonction de l'API (ou de l'ensemble d'API). De toute évidence, cette approche nécessite un certain temps initial consacré à la planification. Cette phase vise à s'assurer que lorsque vient le temps de commencer à coder, les développeurs écrivent du code qui n'aura pas besoin d'être supprimé et réécrit plus tard. Cela permet de créer des API itératives et utiles qui, à leur tour, conduisent à un meilleur programme d'API plus évolutif - et à la valeur pour votre entreprise - dans son ensemble.

Quelle que soit l'approche que vous choisissez, la chose la plus importante à laquelle vous devez réfléchir est de savoir comment offrir des expériences positives aux parties prenantes, y compris les utilisateurs finaux, les développeurs tiers ou internes, et même les personnes du reste de l'entreprise qui peuvent avoir un rôle. Je pense aux API comme des ambassadeurs technologiques - le visage numérique d'une marque - car elles forment un réseau de connexions internes et externes. Et en tant que tels, ils doivent être conçus et fabriqués avec soin, comme tout autre produit ou service proposé par votre entreprise.

Les programmes d'API réussis engagent les utilisateurs dès le début et les maintiennent impliqués dans le processus de conception pour garantir des pistes de développement conformes aux attentes des utilisateurs. Cette étape est tout aussi importante pour les API internes et externes. Les utilisateurs impliqués dans le processus sont susceptibles de devenir les premiers utilisateurs qui conduiront initialement à l'acceptation et à l'utilisation du produit.

Les avantages d'une approche Design-First pour le développement d'API

« Mais, Steve ! (vous vous demandez peut-être) Comment cette approche peut-elle bénéficier aux développeurs, aux utilisateurs finaux, aux partenaires internes, etc. ? » Excellente question. Commençons par l'atout de développement d'API le plus précieux : les développeurs.

• Amélioration de l'expérience des développeurs : l'approche Design-First présente de nombreux avantages, mais l'un des plus importants, et (oserais-je dire "le plus en vogue"), est de loin la création d'une expérience positive pour les développeurs. Ayant moi-même suivi le chemin du développement, je peux vous dire qu'être chargé de réparer des API mal écrites est un cauchemar.

Sans conception intentionnelle, le processus de développement peut devenir chaotique, maladroit et décousu. Cela crée des déconnexions entre les développeurs, les équipes de sécurité, de gouvernance et de documentation. Le résultat final est une énorme pression sur les épaules des développeurs pour pousser une API jusqu'au bout.

Les spécifications, la gouvernance, la conception, le développement et la documentation de l'API partent de la même page et sont développés et maintenus simultanément en adoptant une approche design-first. Cette coordination intégrée permet aux développeurs de rester concentrés sur le développement de solutions et les empêche de ralentir en raison du travail de nettoyage de l'API. L'approche Design-First est conviviale pour les développeurs, les gardant engagés et concentrés sur le résultat final, sans être distraits ou retardés par des API mal écrites et incohérentes. En fin de compte, des développeurs heureux = un programme API heureux.

• Efficacité de l'ingénierie et réduction des coûts : lorsque des composants de qualité sont développés et maintenus à l'aide d'une approche design-first, ils peuvent être réutilisés pour de futures API. Vous n'avez besoin de créer chaque composant qu'une seule fois, ce qui permet à votre équipe technologique d'économiser une tonne de temps et d'argent. La réutilisabilité de tous les composants permet de réaliser d'importantes économies sur le temps de développement tout en mettant les nouvelles API sur le marché plus rapidement.


• Amélioration de la sécurité des API : bien que les API se soient développées au cours des dernières années, cela en fait également une cible de choix pour les pirates et les logiciels malveillants en raison de leur visibilité et de leur réputation de défauts de conception et de vulnérabilités. Sans une conception appropriée en place, les endpoints d'API exposés peuvent être facilement exploités par des pirates. En tant que leader technologique, la sécurité est toujours une de mes principales préoccupations, et une conception intentionnelle garantit que la sécurité est intégrée à votre stratégie d'API dès le début.


• Meilleure coordination entre les équipes internes : les grandes équipes interfonctionnelles sont notoirement difficiles à coordonner, et il est encore plus difficile d'amener des parties prenantes supplémentaires à mi-parcours et de garder tout le monde sur la même longueur d'onde. Avec cette approche, les parties prenantes concernées sont impliquées dès le départ et peuvent apporter leur contribution au développement de l'API. L'inclusion de toutes les parties prenantes, même celles qui peuvent être des utilisateurs non techniques de cette API, garantit que l'API est conçue pour être inclusive et répondre à tous les besoins possibles.


• Opportunités d'innovation et de croissance accrues : les API sont des catalyseurs de croissance, d'innovation accrue et d'expériences utilisateur améliorées. Il est plus facile que prévu de passer d'un processus coûteux et inefficace à quelque chose qui fonctionne mieux pour vos développeurs, vos clients et vos résultats. Plus de 40 % des grandes entreprises déclarent aujourd'hui utiliser 250 API ou plus, selon le rapport Developer Survey 2020, et cette opportunité de croissance continue ne fera qu'augmenter. On estime que 2000 nouvelles API publiques sont publiés quotidiennement.

Avec la prolifération et la généralisation des API, elles touchent désormais pratiquement tous les secteurs, industries et lieux dans le monde. En tant que point d'intégration désigné entre les technologies (par leur nom !), les API sont répandues dans toutes sortes d'entreprises, des constructeurs automobiles aux services de santé. Par exemple, l'un de nos plus gros clients est un fabricant mondial de bière. Je vais "sortir sur une branche" et dire : ce n'est pas la première entreprise à laquelle vous pourriez penser en tant que leader dans la conception et le développement d'API.

Nous savons que ce n'est pas une blague que bon nombre des opportunités d'innovation les plus importantes - dans tous les secteurs et dans les secteurs public et privé - passent par les API. C'est pourquoi il est essentiel qu'ils soient conçus correctement pour évoluer avec cette croissance.

D'accord, mais est-ce que Design-First fonctionne réellement ?

Je comprends; vous ne voudrez peut-être pas me croire sur parole que la design-first change la donne pour votre programme d'API, mais voici quelques histoires qui parlent d'elles-mêmes.

Transact, est une entreprise de technologie de services de campus. Ils ont réduit de 80 % leur temps de développement d'API en adoptant l'approche Design-First pour leur programme d'API. (Vous vous souvenez de l'efficacité du temps et des économies que j'ai mentionnées précédemment ? Voilà.)

"Encore mieux que la réduction du temps de développement, la collaboration accrue avec d'autres équipes lorsque nous utilisons l'approche design-first, nous recevons des commentaires plus tôt et le résultat finit par être plus soigné et professionnel", a déclaré Paul Trevino, Senior Engineering Manager à Transact.

Un autre, Calendly, le logiciel de planification de réunions (que je n'hésite pas à admettre que j'utilise constamment), dispose d'une équipe API qui a construit une toute nouvelle plate-forme API en utilisant une approche design-first.

"L'approche design-first, pour nous, conduit à une implémentation, une cohérence, une gouvernance et une documentation de meilleure qualité qui ne sont jamais obsolètes. C'est quelque chose qui parle définitivement aux développeurs qui produisent et utilisent l'API ; une documentation qui n'est jamais obsolète et de haute qualité, détaillée, tout ce que vous attendez d'une plate-forme mature", a déclaré Dmitry Pashkevich de Calendly, un Application Architect.

Comment mettre en œuvre une approche Design-First

D'accord, donc vous êtes resté avec moi aussi longtemps, ce qui signifie que vous êtes probablement prêt à entendre comment vous pouvez implémenter l'une de ces approches Design-First sophistiquées dans la stratégie API de votre propre organisation. Se concentrer sur la gouvernance décentralisée, l'automatisation accrue et la cohérence grâce à un outil tel que les guides de style vous mènera sur une voie de réussite de Design-First et améliorera votre programme d'API en minimisant la complexité pour les consommateurs d'API.

Commencez par la cohérence et la bonne gouvernance

Ils disent que si vous n'avez rien d'autre que votre nom ou votre réputation, au moins vous pouvez avoir de la cohérence. Il y a une raison pour laquelle une entreprise comme Starbucks réussit si bien : c'est parce que nous savons à quoi nous attendre. Il est réconfortant de vivre une expérience prévisible, peu importe où vous vous trouvez dans le monde lorsque vous y entrez.

Ce qui est vrai pour les interfaces humaines du monde réel telles que Starbucks est également vrai pour les API. Il est essentiel de garder la conception d'une API cohérente - pour en faire une expérience prévisible. Comme nous le disons ici chez Stoplight, la cohérence est la principale différence entre un ensemble d'API et quelque chose qui ressemble à une plate-forme cohérente.

Pour renforcer la cohérence et maintenir cette conception réfléchie, la mise en œuvre de directives dans votre stratégie d'API permettra d'appliquer des normes. Les guides de style d'API sont des instructions facilement consommables pour toutes les informations pertinentes dont un développeur ou une équipe de développeurs aura besoin pour créer ou travailler avec des API. Les références du guide de style fournissent généralement une compréhension de base des API, de ce qu'elles sont et des meilleures pratiques pour les créer, les utiliser et les appliquer dans votre organisation.

Cette cohérence s'accompagne d'un besoin de gouvernance solide de votre programme d'API. La standardisation tombera bientôt à l'eau si votre programme n'est pas conçu avec la gouvernance des API à l'esprit. La gouvernance des API consiste à appliquer des règles et des politiques à vos API, telles que des descriptions, des contrats, des conceptions, des protocoles, des révisions, etc. Cette normalisation dans la conception de votre API permet de garantir que toutes vos API restent cohérentes même lorsque différents développeurs conçoivent et construisent eux. Un programme de gouvernance efficace aide les organisations à s'assurer que chaque API est de haute qualité et détectable, qu'elles créent quelques API ou quelques milliers.

Voyez vos API en tant que produits

La prochaine étape dans l'application de Design-First consiste à vous assurer que vous considérez vos API comme des produits. API-as-a-Product est un concept de développement logiciel établi et de plus en plus populaire, ce qui signifie essentiellement que vous exploitez votre API avec un objectif qui ressemble à tout autre produit que quelqu'un consomme ou utilise. Les API, comme les produits, doivent être faciles à utiliser et activement maintenues et prises en charge.

Le processus de conception d'API comprend les décisions de planification et d'architecture que vous prendriez pour un produit. Tout comme la conception de produits, la conception d'API informe l'expérience utilisateur, et de bons principes de conception répondent aux attentes initiales et continuent de se comporter de manière cohérente et prévisible.

Obtenir l'adhésion des parties prenantes

L'une des parties les plus importantes de la mise en œuvre d'une approche Design-First est de gagner la faveur de toutes les parties prenantes concernées (ce qui est, encore, le principal point de fonctionnement à partir d'une approche Design-First). Créer la base de votre programme d'API signifie que vous avez besoin de l'adhésion des développeurs, de la direction, des commentaires des premiers utilisateurs finaux et des opinions de tous les autres partenaires ou personnes internes susceptibles d'interagir avec l'API.

Ma recommandation pour courtiser les chefs d'entreprise est de se concentrer (sans surprise) sur la valeur métier, idéalement, y compris des mesures solides et un proof-of-concept. Même si vous n'avez qu'un minimum de données à montrer au début, remontez-les dans la chaîne et montrez une amélioration constante au fil du temps. L'élan parlera de lui-même au fur et à mesure que vous lancerez le bal. Une fois que vous avez obtenu cette adhésion, réfléchissez à la manière de transformer ce mandat en transformation de l'organisation et aux acteurs clés nécessaires pour y parvenir.

Pour séduire les développeurs, créez un espace sûr dans lequel ils se sentent à l'aise pour exprimer leurs opinions et un espace pour tester ce qui fonctionnera (avec un ensemble de guidelines, bien sûr). Trouvez des parties prenantes ayant un poids relationnel au sein d'une organisation de développement et établissez un moyen de collaborer avec elles sur votre stratégie d'API (mieux activé via un outil de conception d'API, pourrais-je ajouter sans vergogne). Votre équipe de programme API doit être multidisciplinaire, avec un large éventail d'expériences, de cas d'utilisation et de compétences.

Enfin, assurez-vous d'obtenir les commentaires des premiers utilisateurs et des utilisateurs finaux (tout au long) sur l'expérience réelle de consommation de l'API. Gardez à l'esprit que s'il n'est pas utilisé, il n'est pas utile, il doit donc être une expérience positive. Les développeurs peuvent parfois perdre de vue cette expérience de l'utilisateur final, mais une approche axée sur la conception garantit que cela reste toujours une priorité.

Alors, vous ai-je convaincu ?

J'apprécie que vous vous joigniez à moi pour plonger dans la découverte de Design-First. J'espère que vous pouvez maintenant voir à quel point c'est une clé de voûte pour garantir un programme solide, robuste et facilement évolutif - ou, diable, votre chef-d'œuvre - API et même programme API. (Et, si vous choisissez de ne pas tenir compte de mon avertissement, voici que se passe-t-il lorsque vous ne suivez pas une approche Design-First.)

Donc, si vous avez besoin d'un guide pour vous lancer, je vous recommande fortement (bien que je sois partial) de consulter les ressources de Stoplight autour de la conception d'API.

Dans l'ensemble, nous savons que les API prennent d'assaut le monde et presque tout le monde cherche un moyen de créer des programmes efficaces pour innover et développer leur entreprise. À présent, j'espère que vous pouvez voir que vous ne créerez pas un chef-d'œuvre d'API si vous ne concevez pas d'abord.

Personnellement, j'aime à penser que les développeurs sont parmi les meilleurs designers et créateurs au monde, et j'ai hâte de voir ce qui sera créé ensuite avec l'approche Design-First à l'esprit.