La bonne conception des API est un sujet récurrent pour les équipes qui tentent de perfectionner leur stratégie en matière d’API. Car une API bien conçue permet une meilleure expérience, une documentation plus rapide et une meilleure adoption de votre API. Mais qu’est-ce qui entre exactement dans une bonne conception d’API ? Dans ce billet, nous allons détailler quelques bonnes pratiques pour une conception d’API réussie.
Le design des API est un travail à part entière. Une conception bâclée, basée sur le terrain plutôt que sur l’analyse, avec des API inventées à la volée, sans recul, produit généralement une expérience développeur pauvre, avec le risque que l’API soit peu ou mal utilisée, ce qui irait à l’encontre de sa raison d’être.
La raison est simple : OpenAPI permettant la génération de la documentation de manière automatisée, la documentation sera notamment le reflet des choix de conception. Une mauvaise conception sera donc difficile à interpréter, voire illisible.
La façon dont on expose l’information via l’API a autant d’importance que la capacité à l’exposer de manière sécurisée et fluide. La conception prend ainsi le dessus dans le processus de construction des API. On parle de Design-First. Il ne s’agit ni plus ni moins que de poser les plans de l’API avant d’entrer dans la production de la première ligne de code.
Transversalité et Design-Thinking
Concernant les API, l’enjeu est celui de la transversalité : en incorporant le design en amont, on peut rencontrer les parties prenantes de cette API, et construire celle-ci en respectant la majorité des exigences formulées. Sans ce travail, on aboutirait à une première version qui suivrait les préconisations d’une seule catégorie d’utilisateurs, et les évolutions ultérieures obligeraient probablement rapidement à faire fi de ce premier contrat dans des proportions parfois non négligeables.
Cette transversalité s’organise généralement dans des sessions de Design-Thinking appliquées aux API, qui s’accommodent particulièrement bien qu’une API rend un service et est décrite comme un produit. Astrakhan propose dans son prochain catalogue de formation Digital-Leadership un module Design-Thinking appliqué aux APIs, ainsi que Design-Thinking appliqué à la Data.
Le principal apport du Design-Thinking est de limiter les effets du biais le plus évident : une API construite pour refléter les systèmes auxquels elle se connecte, davantage que les points de vue de ceux qui vont l’utiliser. Les parcours client dans la banque ou l’omni-canal Online+Offline (O+O) dans le Retail tireront parti de cette approche.
L’approche de conception est ensuite complètement architecturale, puisqu’elle va consister à construire progressivement l’API cible en rapprochant l’ensemble des demandes. La collaboration initiale laisse ainsi place temporairement au savoir-faire de l’architecte qui va rapprocher au mieux les demandes de façon cohérente.
On peut se demander si cette approche est liée à l’utilisation de REST et si GraphQL ne va pas rendre toute cette approche caduque. Cela ne semble pas être le cas. Certes GraphQL est plus facile d’accès et propose une meilleure expérience développeur de prime abord. Cependant, selon nous, le travail de Design doit rester agnostique des choix d’architecture et se situer en amont, d’autant que les questions de scalabilité qui entourent GraphQL rendent difficile de l’envisager comme une solution propre à couvrir tous les cas d’usage.
Conventions et règles
Ensuite, il est généralement utile et nécessaire de s’appuyer sur les conventions mises en place afin de faciliter l’approche de votre API par ses futurs utilisateurs. Si les conventions changent d’une API à l’autre, il sera mal perçu d’avoir à rentrer dans plusieurs techniques de Design parfois opposées.
L’utilisation de noms pour les ressources, l’utilisation cohérente des verbes http, la réinterprétation des statuts http de manière univoque, la répartition des informations d’une manière unique entre header, paramètres, variables, body…, sont autant de pratiques à privilégier pour que toutes vos API aient la même signature.
Au-delà, il s’agira également de normaliser les pratiques de paging, de filtres, de liens hypermédias… ou de préciser les options recommandées et disponibles.
Les liens avec l’architecture d’entreprise
D’une manière générale, cela revient à lier la conception des API aux modèles d’information, donc à lier implicitement ces dernières à des travaux préalables de modélisation, ce qui n’est pas en soi révolutionnaire, puisque cela prévalait déjà au temps des architectures de services, pourtant aujourd’hui si décriées.
D’une manière générale, c’est le lien avec les travaux d’architecture d’entreprise et les référentiels où ils sont implémentés qu’il faut utiliser. Cela constitue une bonne façon de garantir la compatibilité et la réutilisabilité des travaux. Astrakhan travaille actuellement à implémenter sur la solution de son partenaire Ardoq un vertical de management des API.
On peut y voir un signe des temps et d’une certaine normalisation, où de nouvelles technologies ont pris le dessus sur d’anciennes, tout en perpétuant au final les éléments de méthode qu’elles prétendaient pouvoir éviter.
Ce qui n’a pas trop d’importance et est plutôt une bonne nouvelle, dans la mesure où cela indique une tendance à la modélisation, à la normalisation, à la définition de règles, pour une économie digitale autrefois fière de n’en respecter aucune. Mais peu importe puisque celle-ci a raflé la mise et tout modernisé avec bonheur sur son passage.
