La conception d'API, qu'est-ce que c'est ?

La conception d'API désigne le processus de développement d'interfaces de programmation d'applications (API) qui mettent les données et les fonctionnalités d'applications à la disposition des développeurs et des utilisateurs. Les API jouent un rôle important dans le fonctionnement des entreprises modernes, avec les nouvelles capacités qu'elles ajoutent à tous les niveaux : exploitation, produits, stratégies de partenariat. Aujourd'hui, si les entreprises ont compris l'intérêt des API, elles se demandent toujours comment les adopter.

Pour être efficace, un programme d'API doit s'appuyer sur la stratégie globale de l'entreprise et contribuer à la réalisation de ses objectifs. Vous saurez que votre stratégie est solide si vous pouvez répondre clairement aux trois questions suivantes :

1. Pourquoi voulons-nous implémenter des API ?
2. Quels résultats concrets attendons-nous de ces API ?
3. Comment prévoyons-nous de mettre en œuvre notre programme d'API pour y parvenir ?

Pourquoi ?

Cette question est souvent mal comprise. Premièrement, plutôt que de se concentrer sur la valeur de l'API en soi, il vaut mieux se poser la question de son effet. N'oubliez pas que c'est l'activité d'une entreprise qui a de la valeur, pas forcément ses API. Une API prend de la valeur lorsqu'elle devient un canal offrant de nouveaux modes d'accès à la valeur déjà proposée par une entreprise.

On croit souvent à tort qu'une API ne peut avoir de valeur que si ses utilisateurs acceptent de payer pour y avoir accès. Ceci n'est vrai que si l'API en soi constitue le produit. Pour la plupart des modèles, ce n'est pas le cas. Les API servent généralement à améliorer d'autres résultats (ventes, parrainage d'entreprises affiliées, notoriété de marque, etc.). Pour les utilisateurs, la valeur tient au résultat d'un appel d'API (demande de service et réponse) et non à l'appel en lui-même.

Selon un sondage mené auprès de 152 entreprises par le Cutter Consortium et Wipro, les facteurs commerciaux les plus souvent retenus pour justifier la mise en place d'un programme d'API sont le développement de nouveaux partenariats, l'augmentation des revenus, l'exploitation de nouveaux modèles commerciaux, l'amélioration des délais de mise sur le marché et le développement de nouveaux canaux de distribution. Les principaux facteurs technologiques sont l'amélioration de l'intégration des applications, l'amélioration de l'intégration mobile et la prise en charge de la connexion à un plus grand nombre d'appareils. Les avantages doivent être suffisamment intéressants pour qu'une entreprise décide spontanément d'investir dans des API.

Quoi ?

La deuxième question doit être « Quels résultats concrets attendons-nous de ces API ? ». En d'autres termes : « Que feront ces API, concrètement, et quel sera leur impact sur l'ensemble de la stratégie commerciale ? ».

Les visions interne et externe d'une entreprise peuvent vous aider à mieux définir la nature de votre future API. La vision interne fait référence aux ressources spécifiques et utiles dont dispose une entreprise. Plus les services et les ressources proposés ont de la valeur et sont uniques, plus ils sont adaptés à un programme d'API.

Une entreprise qui possède des données uniques peut tirer parti de cette ressource en autorisant l'accès aux données par l'intermédiaire de l'API. En proposant des contenus, des données et des services uniques, l'accès à l'API prend beaucoup de valeur.

Au moment de décider du rôle qu'une API doit jouer pour une entreprise, il est important de tenir compte à la fois de la vision interne et de la vision externe
. La décision finale est généralement un compromis entre les deux.

Concrètement, si le « pourquoi » a peu de chances d'évoluer, le « quoi » peut varier de façon significative sous l'influence de facteurs externes, comme les marchés, des considérations techniques ou les conditions économiques. De plus, les orientations internes concernant la valeur d'une ressource peuvent changer, ce qui est aussi susceptible d'affecter la fonction assignée à une API.

Comment ?

La dernière question est « Comment concevoir le programme de l'API pour atteindre l'objectif désiré ? » et porte sur l'implémentation et l'exécution.

Les équipes doivent se poser plusieurs questions :

• Quelle sera la technologie utilisée pour créer les API ?
• Comment seront conçues les API ?
• Comment leur maintenance sera-t-elle assurée ?
• Comment se déroulera leur promotion au sein de l'entreprise ou en externe ?
• Quelles sont les ressources disponibles ?
• Qui doit faire partie de l'équipe ?
• Comment mesurer nos résultats par rapport aux objectifs commerciaux fixés ?

Une équipe API s'apparente à une équipe produit : que vos clients soient internes ou externes, cette équipe est responsable de la création, du déploiement, de l'exploitation et de l'optimisation de l'infrastructure sur laquelle d'autres équipes se reposent.

À l'instar des équipes produit, les équipes API peuvent aussi être très diverses, mais elles doivent généralement comprendre un responsable produit qui veille au respect de la stratégie et des objectifs, des membres dédiés à la conception qui appliquent les bonnes pratiques en matière de conception d'API, des ingénieurs qui intègrent les technologies API, et des collaborateurs chargés de l'exploitation qui exécuteront l'API.

Plus tard, d'autres collaborateurs peuvent être appelés à intervenir, par exemple des personnes chargées de l'assistance et de la communauté, des ambassadeurs de l'API, des spécialistes de la sécurité, etc.

John Musser a décrit les 5 « facteurs » déterminants pour la qualité d'une API lors du discours qu'il a prononcé en 2012 à la convention O’Reilly Open Source :

1. Proposer un service ayant de la valeur
2. Se doter d'un plan et d'un modèle économique
3. Rendre l'API simple, flexible et facile à adopter
4. Gérer cette API et évaluer ses performances de façon chiffrée
5. Offrir une assistance développeur de haut niveau

Le premier facteur, proposer un service ayant de la valeur, est particulièrement important pour répondre à la question « pourquoi » de votre programme d'API. La proposition de valeur joue un rôle essentiel dans le succès d'une API. Si une API a une mauvaise proposition de valeur (ou n'en a aucune), il sera très difficile, voire impossible, de trouver des utilisateurs.

Presque n'importe quelle entreprise qui possède un produit, numérique ou physique, peut générer de la valeur
grâce à une API, si celle-ci est associée à des offres existantes et les améliore. Tant que l'API est structurée de façon à couvrir des cas d'utilisation pertinents du point de vue des développeurs, elle apportera de la valeur.

Identifier et décrire la valeur de votre API est un processus itératif. La première étape consiste à décrire les tâches que vos utilisateurs souhaitent accomplir. Par exemple :

• Envoyer automatiquement des messages aux membres d'une équipe en cas d'urgence
• Sauvegarder des fichiers importants pour prévenir tout risque de perte
• Recueillir des échantillons de données pour détecter certains événements

L'étape suivante consiste à identifier les difficultés spécifiques rencontrées par les utilisateurs avant, pendant ou après les tâches qu'ils ont à accomplir :

• Assurer la fiabilité des envois par tentatives répétées, détecter les échecs, redouter d'avoir envoyé plusieurs messages au lieu d'un seul, réussir à intégrer différents systèmes de messagerie en fonction de l'emplacement de l'utilisateur
• Assurer la bonne réception des fichiers tout en minimisant la quantité de bande passante utilisée
• Gérer d'énormes quantités de données et parvenir à établir des corrélations en temps réel

La troisième étape consiste à faire la synthèse des avantages que vous pouvez offrir à l'utilisateur :

• Envoyer d'autres types de notifications visant à dégager des opportunités plutôt qu'à signaler des risques
• Se débarrasser de certains de ses équipements de stockage si la fiabilité répond à ses besoins
• Automatiser des actions déclenchées par des événements

Lorsque vous réfléchissez à ces difficultés, dressez une liste de tout ce dont un utilisateur peut avoir besoin, notamment l'assistance, la documentation ou les portails pour développeurs. Ensuite, déterminez la façon dont vous avez l'intention d'éliminer ou de réduire certaines des difficultés rencontrées par les utilisateurs de l'API avant, pendant ou après l'accomplissement de leurs tâches, ou des obstacles qui empêchent l'exécution de leur travail. Enfin, déterminez la manière dont vous pensez apporter des avantages (quelle que soit leur nature) aux utilisateurs de votre API.

Au terme de ce processus, nos trois exemples peuvent aboutir aux résultats suivants :

• Une API de messagerie sur plusieurs canaux avec un appel unique pour envoyer des messages et la possibilité de réitérer l'envoi jusqu'à confirmation de la réception des messages (p. ex. : Twilio, PagerDuty)
• Une API de synchronisation de stockage avec des appels optimisés pour vérifier de façon efficace si de nouvelles versions doivent être synchronisées (p. ex. : Bitcasa, Box)
• Une API capable de rassembler différentes sources de données sous forme de flux configurable que vous pouvez filtrer, analyser ou manipuler facilement (p. ex. : GNIP, DataSift)

Pour terminer, vous pouvez vous livrer à un exercice de clarification utile : rédigez plusieurs affirmations qui démontrent l'utilité de l'API pour le profil d'utilisateur visé. Si vous avez du mal à trouver des arguments, cela signifie qu'il faut revoir le modèle de l'API. Il est peut-être nécessaire d'ajouter, de revoir, de préciser ou d'éliminer certaines fonctionnalités de votre API. Il est également possible que votre API offre une valeur importante, mais que vous ne visez pas les bons utilisateurs.

Lorsque vous synthétisez tous vos arguments sous la forme d'une description générale, vous obtenez la proposition de valeur de vos API. Dans le cas de l'API de messagerie décrite ci-dessus, celle-ci peut prendre la forme suivante :

Notre API de messagerie permet aux développeurs en entreprise de bénéficier d'une fonctionnalité de messagerie texte fiable, garantie et sans latence pour les applications professionnelles les plus stratégiques. L'API est également prise en charge par les kits de développement logiciel (SDK) qui correspondent aux langages de programmation les plus utilisés pour une intégration plus rapide.

Dans certains cas, ce processus vous semblera trop compliqué pour créer une simple API interne. Cependant, il est essentiel de s'intéresser à la valeur, même pour les cas d'utilisation en interne. Une proposition de valeur mal définie ne vous permettra pas de convaincre facilement les autres équipes d'adopter votre API. Une proposition de valeur bien définie facilitera l'adoption et permettra à votre API de devenir un atout majeur de votre entreprise.

Pour mieux définir la valeur de votre programme d'API, posez-vous les cinq questions suivantes :

1. Qui est l'utilisateur ? Répondez à cette question en tenant compte de la relation que vous entretenez avec l'utilisateur (client, partenaire, développeur externe), de son rôle (spécialiste des données, développeur pour mobiles, responsable d'exploitation) ainsi que de ses contraintes ou préférences.
2. Quels sont les problèmes que vous cherchez à résoudre ou les avantages que vous apportez aux utilisateurs ? Répondez à cette question en tenant compte de l'activité du client, de ses difficultés et des avantages qu'il peut tirer au regard de la proposition de valeur. Demandez-vous également si vous répondez à un besoin critique (difficulté, opportunité de revenus) et quel indicateur mesurable est amélioré pour l'utilisateur (rapidité, revenus, économies, possibilité d'innover).
3. Quels sont les cas d'utilisation pris en charge par votre API ? Identifiez, à l'aide de la proposition de valeur, les solutions les plus efficaces (pour l'utilisateur et votre entreprise) que votre API peut apporter pour résoudre les problèmes de vos utilisateurs ou les aider à saisir de nouvelles opportunités. Gardez à l'esprit ces cas d'utilisation lors de la création de votre API.
4. Comment augmenter la valeur pour l'utilisateur au fil du temps ? Pensez aux éventuels changements futurs lors de la rédaction de votre proposition de valeur. Quels sont les jalons importants en matière de changements internes ou externes ?
5. Quelle est la valeur créée pour votre entreprise en interne ? Pensez aux avantages procurés en interne et à la valeur que l'API peut apporter à l'entreprise.

La formulation de la valeur d'une API est une étape importante dans la conception de votre programme basé sur les API. Toutefois, les API génèrent également des coûts qu'il vous faut compenser par de la valeur. Même si cette valeur ne peut être mesurée en termes financiers, elle doit être concrète, par exemple :

• Quelle est l'activité principale de l'entreprise ?
• Comment une API peut-elle optimiser ou développer cette activité ?

Dans certains cas, les API peuvent faire naître des opportunités commerciales entièrement inédites, étrangères au modèle actuel d'une entreprise. Mais même dans ces cas, ces API s'appuient généralement sur des ressources ou une expertise existantes pour ouvrir de nouveaux horizons.

En résumé, voici les trois raisons pour lesquelles il est important de définir un modèle économique probant pour concevoir des programmes d'API performants :

1. Avec un modèle économique adéquat, il devient possible de mettre l'accent sur la valeur de l'API pour l'entreprise, et ainsi de justifier des engagements à long terme en faveur du programme d'API. Sans ces engagements, il est rare d'obtenir les ressources requises pour accomplir les tâches nécessaires à la mise en place et à l'exécution d'un programme d'API efficace.
2. Avec un modèle économique adéquat, vous pouvez définir la fonctionnalité du produit, ce qui est nécessaire pour répondre aux besoins des tiers et stimuler votre activité.
3. Avec un modèle économique adéquat, vous garantissez la prise en compte des rôles et responsabilités dans l'entreprise ainsi que l'identification des collaborateurs qui bénéficient des différents aspects de la valeur générée par l'API. Cela demande aussi de définir les avantages dont bénéficient les utilisateurs de l'API et de les évaluer à l'aune des bénéfices pour le fournisseur d'API.

Une conception d'API de qualité suit certains principes de base, qui peuvent varier lors de la mise en œuvre. On peut comparer cela aux différences entre les voitures : si elles sont toutes dotées d'un volant, d'une pédale de frein et d'une pédale d'accélération, l'emplacement des feux de détresse, du mécanisme d'ouverture du coffre ou de la radio peut varier d'un modèle à l'autre. Il est toutefois rare qu'un conducteur expérimenté ne parvienne pas à maîtriser une voiture de location.

C'est ce niveau de design intuitif que visent les équipes chargées des API : elles souhaitent fournir des API qu'un utilisateur expérimenté peut utiliser sans explication, ou très peu.

Simplicité

C'est le contexte qui détermine le degré de complexité d'une API. Une conception particulière peut être simple dans un certain cas d'utilisation, mais très complexe dans un autre. Il est donc important de trouver un juste équilibre au niveau des méthodes de l'API. Pour ce faire, envisagez la simplicité à différents niveaux, notamment :

• Le format des données : prise en charge XML, JSON, de formats propriétaires ou d'une combinaison de ces formats.
• La structure de la méthode : les méthodes peuvent être très génériques, pour obtenir des ensembles de données générales, ou très spécifiques, pour permettre des requêtes ciblées. Les méthodes sont aussi généralement appelées selon une certaine séquence pour répondre à certains cas d'utilisation.
• Le modèle de données : le modèle de données sous-jacent peut être très proche ou très différent de ce qui est réellement présenté via l'API. Ce choix a un impact sur la facilité d'utilisation et de maintenance.
• L'authentification : les différents mécanismes d'authentification ont chacun leurs forces et leurs faiblesses. Faites votre choix en fonction du contexte.
• Les politiques d'utilisation : les autorisations et les quotas imposés aux développeurs doivent être faciles à comprendre et à intégrer.

Il peut être difficile de créer une API qui soit à la fois simple et flexible. Une API trop axée sur la simplicité risque d'être trop spécialisée, de ne correspondre qu'à des cas d'utilisation très spécifiques et de ne pas être suffisamment flexible pour s'adapter à d'autres cas.

Pour lui donner une certaine flexibilité, commencez par identifier les éléments sur lesquels repose l'espace des opérations potentiel, y compris les systèmes et modèles de données sous-jacents, puis déterminez quel sous-ensemble de ces opérations est réalisable et utile. Voici comment déterminer le juste équilibre entre simplicité et flexibilité :

• Essayez d'identifier les opérations atomiques. La combinaison de différentes opérations atomiques peut permettre de couvrir tout l'espace des opérations.
• Identifiez les cas d'utilisation les plus répandus et utiles. Créez une deuxième couche de métaopérations qui combine différentes opérations atomiques pour répondre à ces cas d'utilisation.

Le concept HATEOAS (Hypermedia As The Engine of Application State) peut sans doute aussi améliorer la flexibilité, puisqu'il permet des modifications d'exécution dynamiques dans l'API et dans les opérations du client. La contrainte HATEOAS augmente donc bien la flexibilité en facilitant la gestion des versions et la documentation. Mais de nombreuses questions doivent être prises en compte dans la conception de l'API.

Afin de réfléchir à la conception de votre API, posez-vous les cinq questions suivantes :

1. Avons-nous conçu l'API pour prendre en charge nos cas d'utilisation ? Une fois identifiés les principaux cas d'utilisation, vous devez concevoir votre API de façon à ce qu'elle y réponde. La flexibilité est un aspect important à prendre en compte pour éviter d'exclure certains cas d'utilisation qui, bien que moins fréquents, doivent être pris en charge pour laisser une porte ouverte à l'innovation.
2. L'architecture REST est-elle justifiée ?Les API REST sont à la mode, mais ce n'est pas une raison suffisante pour les adopter. Certains cas d'utilisation s'y prêtent parfaitement, mais d'autres demandent un style d'architecture différent, par exemple GraphQL.
3. Est-ce que nous exposons notre modèle de données sans tenir compte des cas d'utilisation ? Une API doit reposer sur une couche d'abstraction exploitant votre modèle de données actuel. En règle générale, n'autorisez pas une API à accéder directement à votre base de données, même si cela peut s'avérer nécessaire dans certains cas.
4. Quelles sont les zones géographiques les plus stratégiques ? Avons-nous planifié nos datacenters en conséquence ? La conception de l'API doit également tenir compte d'éléments non fonctionnels tels que la latence et la disponibilité. Choisissez des datacenters proches de la zone géographique où se trouvent la plupart de vos utilisateurs.
5. La conception de l'API prend-elle en compte celle de nos autres produits ? Si l'API n'est pas le seul produit de votre entreprise, assurez-vous d'assurer sa compatibilité avec vos autres produits. Vous êtes libre de concevoir votre API indépendamment de vos autres produits. Dans ce cas, vous devez vous assurer d'indiquer clairement ce choix en interne comme en externe.

Le TTFHW (Time To First Hello World, ou délai avant le premier Hello World) est une mesure clé pour améliorer la conception des API et faciliter leur adoption. Elle indique le temps qu'il faut à un développeur pour obtenir un produit minimal viable à partir de votre API. C'est une excellente façon de se mettre à la place d'un développeur qui souhaite tester votre API et découvrir l'effort à fournir pour obtenir un résultat.

Lorsque vous définissez le début et la fin de la mesure TTFHW, nous vous conseillons de couvrir toutes les dimensions possibles du travail du développeur. Cela vous permettra de procéder aux optimisations nécessaires pour accélérer et simplifier l'utilisation.

Pour les développeurs, une API qui accélère leur travail est une API bien organisée et ils seront rassurés sur sa capacité à fonctionner comme prévu. Si l'API prend trop de temps pour fournir un résultat, elle risque de décourager certains développeurs.

Outre le TTFHW, nous vous conseillons d'utiliser un autre indicateur, le TTFPA (Time To First Profitable App, ou délai avant la première application rentable). Cet indicateur est moins évident, car la définition de la rentabilité peut varier en fonction de votre API et de votre stratégie d'entreprise. Il est utile d'en tenir compte parce qu'il vous oblige à réfléchir aux aspects liés à l'exploitation de l'API dans le cadre du programme de l'API.

Les deux principes au cœur de l'expérience développeur sont :

1. Concevoir un produit ou un service qui offre une valeur claire aux développeurs et apporte une solution ou une opportunité évidentes. Il peut s'agir d'une valeur monétaire ou d'une autre valeur, comme un moyen d'accroître la portée ou la notoriété de la marque, d'étoffer la clientèle, d'augmenter les ventes indirectes, de renforcer la réputation du développeur ou encore simplement d'offrir le plaisir d'une technologie de qualité qui fonctionne.
2. Le produit doit être facilement accessible. Vous pouvez, par exemple, mettre en place un système d'inscription simple ou ne pas imposer d'inscription, proposer un accès à des fonctions de test, fournir une excellente documentation ou offrir une grande quantité de code source gratuit et bien présenté.

Nous pensons que la plupart des programmes d'API devraient inclure une version développeur, que ces API soient disponibles publiquement ou réservées aux partenaires ou collaborateurs internes. Les dispositions peuvent être plus ou moins complexes selon les utilisateurs ciblés.

Portail développeur

Le portail développeurs est l'élément clé d'un programme destiné aux développeurs. Il leur permet de s'inscrire, d'accéder à vos API et de les utiliser. Les développeurs doivent pouvoir accéder facilement à votre API et être en mesure de la prendre en main rapidement.

L'indicateur TTFHW est parfait pour évaluer cet aspect. Pensez aussi à rendre le processus d'inscription aussi fluide, simple et rapide que possible. Une bonne pratique recommandée consiste à autoriser les développeurs à appeler vos API pour observer leur comportement (demande et réponse) sans aucune inscription préalable. Nous vous encourageons également à mettre à leur disposition des contenus additionnels, comme des guides de démarrage, une documentation de référence pour chaque API ou du code source, afin de faciliter la prise en main de vos API.

Accélération grâce aux partenaires de l'écosystème

En tant que fournisseur d'API, vous évoluez dans un écosystème de partenaires et de fournisseurs. Ces partenaires disposent souvent de leurs propres réseaux et moyens de distribution et de communication pour leurs contenus. Nous vous conseillons de rechercher des alliances susceptibles de vous aider à accroître l'adoption de votre API. De telles alliances peuvent se former lorsque des API sont complémentaires et que leur utilisation conjointe peut apporter une valeur aux développeurs.

Voici quelques questions à se poser pour évaluer l'expérience développeur :

1. Comment expliquer la valeur de l'API en cinq minutes ? Préparez une brève présentation de la proposition de valeur de votre API à l'attention des développeurs.
2. Quelle est la valeur des indicateurs TTFHW et TTFPA ? Comment les réduire ? Pour rendre votre API plus conviviale aux yeux des développeurs, réfléchissez à votre TTFHW de bout en bout. Nous vous conseillons de ne pas perdre de vue la valeur de vos indicateurs TTFHW et TTFPA si vous ajoutez des éléments à l'expérience développeur (un portail par exemple) et à chaque fois qu'un aspect de l'API est modifié.
3. Quel est le processus d'inscription pour les nouveaux développeurs ? Est-il aussi simple que possible ? Celui-ci doit refléter les cas d'utilisation de votre API. Naturellement, le niveau de sécurité doit être plus élevé pour accéder aux API ou données sensibles et vous devrez probablement mettre en place des accords plus formels. Pour tout le reste, le processus d'inscription doit rester très simple et direct pour permettre aux développeurs d'obtenir rapidement des résultats (TTFHW).
4. Notre API est-elle suffisamment flexible pour intéresser des développeurs ? Si vous avez trouvé la bonne proposition de valeur et que des développeurs s'inscrivent pour utiliser votre API, félicitations ! N'oubliez pas que si vous aidez vos utilisateurs à obtenir des résultats, vous pourrez les fidéliser et en attirer davantage.
5. Comment offrir une assistance aux développeurs qui rencontrent des problèmes ? Nous sommes partisans d'une approche de libre-service, qui vous permettra d'évoluer plus facilement. Les réponses à de nombreuses questions que se posent les développeurs peuvent être apportées par une documentation de qualité, des FAQ ou des forums. Cependant, le modèle du libre-service a ses limites. Certaines questions plus complexes, ou d'autres complications telles que les problèmes relatifs à la facturation, nécessitent la mise en place d'un système d'assistance.
6. La documentation contient-elle les informations nécessaires pour favoriser l'innovation ? Dans quelle mesure peut-on aider les développeurs qui s'écartent des cas d'utilisation habituels ou qui souhaitent innover ? Les bonnes idées peuvent jaillir de n'importe où.