Une membre du Technical Architecture Group du W3C et ex-instructrice au MIT compare les grands principes de la conception d’une bonne API à ceux des robinets mélangeurs et mitigeurs. Voici de quoi vous en inspirer.
Faire de petits changements à partir d’une API peut parfois s’avérer compliqué. C’est le constat effectué – avec humour – par Lea Verou, consultante, membre du Technical Architecture Group (TAG) du W3C et ex-instructrice au MIT.
« Pour examiner cette question, examinons tout d’abord une citation d’Alan Kay, un célèbre informaticien. Il a dit : “Les choses simples devraient être faciles et les choses complexes devraient être possibles” », relate-t-elle, lors de la dotJS Conference en juin 2024 à Paris. « Cette citation est considérée comme l’un des plus grands principes de conception des API ».
Selon la membre du TAG du W3C, ce précepte peut s’appliquer à tout produit. Et de prendre l’exemple de Google Calendar qui, de manière intuitive, permet de modifier un événement sans forcément manipuler un champ de date.
UX et DX : même combat
Lea Verou considère que les grands principes de conception d’API ne sont pas si différents de ceux qui régissent le design d’interface visuelle, voire qu’ils sont identiques.
« La seule raison pour laquelle ils sont considérés comme des principes de conception d’API est qu’un ingénieur les a formulés pour la première fois », avance-t-elle. « Les API ne représentent qu’un type différent d’interface utilisateur, où les utilisateurs sont des développeurs et où l’interaction implique l’écriture de code », définit-elle.
« Les API ne représentent qu’un type différent d’interface utilisateur, où les utilisateurs sont des développeurs et où l’interaction implique l’écriture de code ».
Lea VerouMembre du TAG, W3C et Consultante
« En fait, il s’agissait d’un concept tellement difficile à assimiler pour de nombreuses personnes que nous ne pouvions pas réutiliser les mêmes mots. […] Pour décrire cela, nous devions inventer une nouvelle expression, l’expérience développeur ou DX », ironise-t-elle.
Dans cette même logique, Lea Verou estime que les concepteurs d’API ne doivent pas imaginer les cas d’usage, mais récolter des informations sur le « point de douleur » à résoudre. Ces cas d’usage peuvent ensuite être classés par niveau, du plus bas au plus haut.
« Un cas d’usage de haut niveau d’un tournevis pourrait être le montage d’un meuble IKEA, tandis qu’un usage de bas niveau pourrait être de serrer une vis », illustre-t-elle. « Avec une API, l’usage de haut niveau pourrait être de valider une adresse physique ou mail et l’utilisation de bas niveau, de faire correspondre des chiffres qui se répètent ».
Entre ces deux extrémités, il y a un ensemble de cas d’usage qui peuvent s’exprimer. « En fait, on peut considérer les cas d’usage comme des tests unitaires de la conception d’API. Plus ils sont diversifiés, plus la conception est robuste, à l’instar d’une véritable suite de tests », déclare Lea Verou.
La « falaise de l’utilisabilité »
Pour autant, cette diversité peut se révéler un véritable cauchemar pour les utilisateurs d’API.
La simplicité est également un piège. Parfois, constate Lea Verou, une API permet de réaliser aisément une tâche simple, mais s’avère dépourvue de contrôles fins.
Elle prend pour exemple l’API JavaScript HTMLVideoElement. Selon la consultante il suffit d’ajouter un seul contrôle d’attribut pour obtenir une barre d’outils élégante et performante avec cette API.
« Mais qu’en est-il si nous voulons aller un peu plus loin ? Et si nous voulions ajouter un sélecteur de sous-titres ou un bouton pour ouvrir la vidéo sur YouTube ou pour afficher les moments clés de la vidéo, ou encore pour faire un saut de 10 secondes en arrière ou en avant. Comme Netflix ? » poursuit-elle. « Rien de tout cela n’est “niche”, mais les contrôles par défaut sont quasi inexistants. Dès que vous avez besoin d’ajouter quelque chose ou de modifier le comportement d’un élément, vous devez recréer toute la barre d’outils à partir de zéro ».
En clair, la courbe de difficulté d’implémentation connaît un pic. « C’est ce qu’en UI l’on appelle la “falaise de l’utilisabilité” », définit Lea Verou. « Et c’est très courant dans les systèmes qui essaient de rendre les choses simples faciles et les choses complexes possibles en proposant deux API distinctes, l’une, de très haut niveau et l’autre, de très bas niveau ».
C’est pourquoi, selon la consultante, « la complexité [d’une API] devrait être dévoilée progressivement. Elle doit être disponible quand vous en avez besoin, mais bien cachée le reste du temps ».
Une histoire de robinets
Il faudrait alors, d’après elle, s’inspirer des robinets mitigeurs. Quand les robinets mélangeurs exposent la complexité d’implémentation sous-jacente avec deux valves – la gestion d’un flux d’eau froide et un autre d’eau chaude –, le mitigeur simplifie ce concept avec une seule commande pour piloter finement le débit et la température.
« En fait, il faut viser une courbe douce où la complexité de l’API augmente graduellement et lentement. Quant aux cas d’usage liés à l’interface utilisateur, plus cette complexité est graduelle, mieux c’est », recommande-t-elle.
« Il faut viser une courbe douce où la complexité de l’API augmente graduellement et lentement. Quant aux cas d’usage liés à l’interface utilisateur, plus cette complexité est graduelle, mieux c’est ».
Lea VerouMembre TAG W3C, Consultante
Pour autant, puisqu’ils reproduisent la logique sous-jacente, les robinets mélangeurs peuvent être plus simples à installer. Et il pourrait en être de même pour les API. Selon elle, « les mélangeurs compliquaient l’utilisation et il en va de même pour les API qui présentent de but en blanc leur complexité ».
« Les robinets les plus récents sont un peu plus complexes à mettre en œuvre en interne, mais ils simplifient les principaux cas d’usage », argue Lea Verou. « Ce n’est pas une coïncidence. Il est bon d’opter pour la cohérence interne plutôt que pour la complexité externe. Cela peut parfois nécessiter de sacrifier la qualité du code, par exemple en utilisant des bidouillages en production. Mais c’est un compromis qui vaut la peine d’être fait », estime-t-elle.
Design d’API : l’utilisateur passe avant tout (ou presque)
Il faudrait alors circonscrire la difficulté par groupe d’utilisateurs. « Donnez la priorité aux utilisateurs sur les intégrateurs à tous les niveaux, et donnez la priorité à chaque être humain sur la pureté théorique », souligne la membre du TAG du W3C. « Cela permet à la fois de minimiser la douleur collective et d’attribuer la responsabilité de la gestion de la complexité au groupe le plus technique ».
En clair, « faites subir la douleur à ceux qui peuvent la supporter », résume-t-elle.
Ainsi, ce ne sont pas aux usagers de maintenir plusieurs sources de vérité, mais à l’API (et aux systèmes sous-jacents) de gérer la bonne synchronisation des données. Et donc aux profils les plus techniques de s’en assurer.
En principe, cette méthodologie donne plus de travail aux ingénieurs et pourrait ralentir le rythme de la livraison logicielle.
« Vous n’êtes pas obligé de tout faire en même temps », nuance Lea Verou. « Vous pouvez livrer une API de haut niveau ou une autre de bas niveau, puis ajouter des couches par-dessus pour faciliter les choses simples ou rendre possibles des choses plus complexes ».
Le choix du point de départ est fonction du groupe d’utilisateurs et des cas d’usage.
« Si les cas d’utilisation sont tous concentrés autour d’un point, alors vous pouvez simplement livrer une API de haut niveau qui couvre environ 80 % des besoins. Puis, dans les versions ultérieures, introduire des primitives de niveau inférieur qui expliquent le fonctionnement de l’API de niveau supérieur, s’il y a une demande suffisante de la part des usagers », relate Lea Verou.
« Si ce n’est pas le cas, il peut être plus sûr de proposer d’abord une API de bas niveau, puis des raccourcis et des abstractions de haut niveau par-dessus. Une fois que vous aurez observé ce que les gens en font ».
Les tests font partie de la conception
Pour autant, selon la consultante, il est plus difficile de prévoir l’usage d’une API que de la concevoir. Afin de gagner en prévisibilité, Lea Verou encourage les équipes de développement à tester dès la conception leurs API.
« Les tests utilisateurs sont essentiels, car vous n’êtes pas l’utilisateur et devez comprendre comment les autres utilisent votre API », assure-t-elle.
« Beaucoup pensent que les tests utilisateurs ne concernent que les interfaces visuelles et sont uniquement le travail des designers UX. Cependant, le concept est similaire pour les API ».
Selon elle, il faut impliquer des utilisateurs représentatifs, leur donner des tâches, observer leurs succès et difficultés, et éviter de les influencer. « Il doit être clair que c’est le design qui est testé, et non l’utilisateur. Il suffit de cinq utilisateurs pour découvrir la plupart des problèmes, et cela peut être fait de manière économique, même via un simple appel Zoom », poursuit-elle.
« Si plusieurs utilisateurs rencontrent des difficultés avec l’API, c’est probablement un problème de conception plutôt qu’une erreur de l’usager ».
« Si plusieurs utilisateurs rencontrent des difficultés avec l’API, c’est probablement un problème de conception plutôt qu’une erreur de l’usager ».
Lea VerouMembre du TAG, W3C et Consultante
Il faut donc procéder par itération. Développer des API « démo », les tester, rédiger la documentation avant de les déployer. Recommencer.
« Enfin, au-delà de tous les principes de conception, l’objectif le plus important est de développer votre empathie pour les utilisateurs. Montrer que vous vous souciez d’eux est essentiel. Pensez aux personnes qui utiliseront les API que vous concevez, à leurs besoins et cas d’utilisation. Facilitez-leur la vie et réduisez leurs difficultés », conclut Lea Verou.
La littérature consacrée au design d’API étant souvent spécifiques à des types d’interface, par exemple GraphQL, REST ou RESTFUL, l’ancienne instructrice au MIT recommande la lecture des ouvrages « The Essence of Software : Why concepts Matter for Great Design » de Daniel Jackson – le livre où elle puise l’exemple des robinets – et « The Design of Everyday Things » de Don Norman.
