Comment être un bon API Designer ?

API Management

Dans cet article, nous analysons ton rôle d’API Designer et les règles à suivre lors de la conception d’une ou plusieurs API mais aussi  les compétences à développer pour mener à bien tes projets, tes différentes qualités et, pour finir, tes potentiels obstacles.

Avant d’expliciter ce qu’est un bon API designer, il nous faut définir ce qu’est le design (aussi appelé conception) d’API.

Il s’agit du processus de définition du périmètre, des ressources nécessaires et des entrées/sorties d’une API permettant aux développeurs et/ou utilisateurs d’avoir à disposition les données et les fonctionnalités d’applications. De nos jours, les interfaces de programmation d’application font partie intégrante du fonctionnement des entreprises. Elles apportent une étendue de potentiel à plusieurs niveaux :  exploitation, produits, services, stratégies de partenariat. Même si ces API semblent être une solution idéale pour moderniser les systèmes des entreprises, il n’est pas toujours évident de savoir comment les adopter. C’est là qu’intervient ton rôle d’API Designer.

Léonard De Vinci, à travers son œuvre intitulée « L’homme de Vitruve », montre la perfection du corps humain. Vitruve disait « Pour qu’un bâtiment soit beau, il doit posséder une symétrie et des proportions parfaites comme celles que l’on trouve dans la nature. ».

Alors, d’après les principes vitruviens, une architecture ou un design parfait devrait se baser sur les 3 critères de la figure ci-dessous :

La version informatique de ces 3 critères vitruviens se traduit par « Fonctionnalité, Convivialité et Expérience ».


Afin de concevoir une API idéale, il faut donc travailler sur ces 3 axes et te poser les bonnes questions en évaluant en amont les différentes fonctionnalités que devra avoir le produit, c’est-à-dire à quelle(s) problématique(s) il répondra mais aussi en déterminant quelles seront ses interactions avec l’utilisateur. Voici quelques-unes des questions à te poser :

  • Fonctionnalité
    • L’API me permettra-t-elle d’accéder aux informations dont j’ai besoin ?
    • Est-ce que l’API fonctionnera lorsque j’en aurai besoin ?
    • Serais-je en mesure de m’y connecter ?
  • Convivialité
    • Combien de temps devrai-je me former pour débuter avec l’API ?
    • Sera-t-il pénible de comprendre son fonctionnement ?
    • Pourrais-je facilement résoudre mes erreurs moi-même ?
  • Expérience (aspect émotionnel)
    • Comment l’API me fait-elle me sentir ?

Ce que tu dois faire

Tu es en charge du design fonctionnel et technique d’API.

Tu dois être capable de :

  • Bien comprendre la vision de l’entreprise et les fonctionnalités principales que l’API doit avoir.
  • Traduire cette vision en une conception API idéale (il est important d’avoir une compréhension claire de la vision métier et de ses fonctions). Réciproquement, un API designer doit être en mesure d’expliquer de manière fluide des interactions techniques en les illustrant avec des exemples réels afin d’être compris par un public non-technique.
  • Recueillir et Formaliser des spécifications fonctionnelles en se mettant dans la peau du consommateur. Tu devras resserrer la boucle de rétroaction avec les consommateurs cibles durant tout le processus.
  • Définir une offre de service adaptée à l’entreprise en intégrant des outils/pratiques de design d’API modernes
  • Etablir les livrables nécessaires pour assurer une bonne documentation pour les développeurs/utilisateurs.
  • Contribuer aux autres livrables nécessaires comme les didacticiels, bibliothèques de code et exemples de code.
  • Faire la conduite du changement.

Ce que tu ne dois pas sous-estimer : l’expérience développeur

L’ expérience utilisateur est souvent mise de côté lors de la conception d’APIs mais c’est une erreur. En effet, une bonne DX permet :

  • Que ton API soit utilisée par davantage de développeurs
  • Que des applications soient mises sur le marché plus facilement

Elle se résume par :

  • Les interactions entre les développeurs et le(s) API Designer(s)
  • L’impact émotif de l’usage de l’API sur le développeur

Les considérations essentielles de la DX sont :

  • L’Education à l’aide de documentation, de démonstrations, d’annotations, d’exemple de code, des SDKs et d’engagement auprès de la communauté des développeurs.
  • Les Interventions/Dépannages permettant de gérer les messages d’erreurs, le suivi des défauts, le temps de réparation et la documentation des erreurs.
  • La Visibilité avec le traçage des transactions, des fonctions de recherche intuitive et l’accessibilité aux applications.
  • La Gestion du changement grâce à l’historique et la gestion des versions de l’API, la rétrocompatibilité et en mettant en place un processus de mise à niveau ou de migration.
  • La Confiance à travers la stabilité de l’API, une communication honnête et transparente ainsi que l’assurance d’une sécurité fiable.

Les obstacles que tu pourrais rencontrer

Il arrive souvent que des problèmes surviennent lors du design d’une API. Pour les contrer au mieux, il te faut les identifier et les prévoir.

  • Des coûts supplémentaires

Lors de la création d’un système de gestion d’API, si l’approche de l’infrastructure n’est pas adapté aux espérances des utilisateurs, des coûts lourds et inutiles peuvent être réquisitionnés.

Faire attention à bien identifier clairement la vision de l’entreprise et du développeur avant de concevoir réellement la solution. 

  • Une sécurité capricieuse 

Il peut arriver un moment qu’un utilisateur ait accès à l’API alors que son statut ne le lui autorisait pas. Cela pourrait mener à des actes malicieux.

On utilise une approche à plusieurs volets comprenant l’utilisation d’une passerelle API. Celle-ci doit être en mesure de valider, autoriser et contrôler facilement l’accès des consommateurs légitimes.

  • Une perspective biaisée 

Lors du développement d’une API, un API designer ne possède que sa propre perspective et construit tout le système selon elle. Le problème est que sa façon de voir les choses  est biaisée et elle n’est du coup, pas toujours partagée avec les utilisateurs du futur système. Cela peut provoquer des difficultés à l’utilisation de celui-ci.

Il est alors primordial de définir un modèle d’utilisation simple et de rédiger une documentation détaillée. Pour cela, on introduit l’opinion utilisateur (les développeurs) sur toute la durée (boucle de rétroaction) du processus de développement du design d’API.

  • Des suppositions erronées

Par ailleurs, un API designer fait souvent des hypothèses quant à l’utilisation de leur futur solution par les développeurs. Il arrive souvent que ces hypothèses soient incorrects.

Pour parer à cette possibilité, le mieux est de concevoir une solution avec un design simple, familier et sécurisé.

De plus, aborder l’évolutivité de l’API tôt dans le processus t’offre la possibilité d’aider à définir le succès futur et la durée de vie de ton API.

Tes qualités

  • Avoir une appétence pour le fonctionnel (compréhension du besoin consommateur) et la technique (recherche de la meilleure solution)
  • Maîtriser des principes fondamentaux des SI et de l’écosystème digital actuel
  • Connaître les meilleurs pratiques/modèles de design d’API modernes ainsi que celles pour l’expérience utilisateur.
  • Avoir des compétences en conduite et pilotage de projets

Les conseils à te donner

  • Se rappeler que les interfaces de programmation applicatives fondent le modèle d’affaire des entreprises digitales.
  • Saisir tous les enjeux, imbrications et conséquences de l’exposition de ses services à des tiers.
  • S’assurer que le client (développeur ou utilisateur) les a, lui aussi, correctement compris.
  • Se remémorer que les choix faits sont pris pour longtemps puisque la durée de vie d’une API est particulièrement longue.
  • Privilégier une conception d’API simple et conviviale et une bonne expérience utilisateur plutôt qu’une cohérence centralisée.

Envie de te former ?

Oreilly. (s.d). Formation sur l’API designer roles and responsabilities. Disponible ici : https://www.oreilly.com/library/view/hands-on-restful-api/9781788992664/1389e6f8-8f46-4a6f-81de-20015c403321.xhtml

API academy. (s.d.). Formation sur l’API Designer. Disponible ici : https://apiacademy.learnupon.com/users/sign_in

Publié le 14/10/21

 


Partagez cet article :