Le problème des clés d'API qui n'expirent jamais
Une clé émise il y a des années, jamais renouvelée et toujours valide aujourd'hui n'est pas une commodité. C'est un risque que personne n'a vraiment examiné depuis des années.
Pourquoi la qualité de la documentation compte plus que le nombre de fonctionnalités
Une page de tarifs qui liste quarante endpoints paraît plus complète qu'une page qui en liste quinze. C'est aussi, souvent, un signal d'alerte. Construire un endpoint ne représente qu'une fraction du travail nécessaire pour le rendre utilisable. Le reste, c'est la documentation : des descriptions de paramètres claires, de vrais exemples de requêtes et de réponses, des remarques honnêtes sur les cas limites et une explication simple de ce qui se passe quand quelque chose tourne mal. Faites l'impasse sur ce travail pour quarante endpoints et vous obtenez quarante fonctionnalités qui existent techniquement et à peine en pratique.
Nous préférons avoir moins de choses bien documentées que davantage de choses mal documentées. Un développeur qui évalue une API lit rarement la liste des fonctionnalités en premier. Il lit la documentation, essaie un exemple de requête et se forge une opinion sur toute l'entreprise en quelques minutes, selon que cet exemple fonctionne ou non tel qu'il est écrit. Si ce n'est pas le cas, le nombre de fonctionnalités affiché sur la page marketing n'a plus d'importance, car la confiance nécessaire pour continuer à lire vient de quitter la pièce.
Pour nous, une bonne documentation signifie quelques choses concrètes, pas un vague engagement. Cela signifie que l'authentification est expliquée en montrant clairement chaque méthode acceptée, et pas seulement celle que le fournisseur préfère. Cela signifie que les limites de débit sont indiquées sous forme de vrais chiffres, et non par « des limites généreuses s'appliquent ». Cela signifie que les codes d'erreur sont listés avec ce qui provoque réellement chacun d'eux, afin qu'un développeur qui débogue une requête échouée trouve la réponse dans la documentation au lieu de la deviner à partir du seul code de statut. Rien de tout cela ne demande plus d'ingénierie. Cela demande que quelqu'un décide que tout écrire clairement n'est pas une corvée facultative greffée sur le vrai produit.
Une documentation simplement passable a aussi un coût qui s'accumule. Un développeur qui ne trouve pas de réponse dans la documentation ouvre un ticket d'assistance, et résoudre cette seule question coûte alors du temps au personnel, en plus du temps d'ingénierie déjà consacré à construire la fonctionnalité. Multipliez cela par suffisamment de clients qui butent sur le même paragraphe peu clair, et les « économies » réalisées en rédigeant une documentation mince deviennent vite négatives. Une documentation claire n'est pas un bonus ajouté par-dessus l'API. Elle coûte moins cher que l'alternative, dès que l'on compte la charge d'assistance qu'engendre un paragraphe peu clair.
Nous pensons aussi que la qualité de la documentation est l'un des rares signaux qu'un client potentiel peut réellement évaluer avant de s'engager dans une intégration. Vous ne pouvez pas facilement vérifier l'historique de disponibilité d'un fournisseur en cinq minutes, et vous ne pouvez pas juger pleinement de la précision des données sans intégrer d'abord. Vous pouvez, en cinq minutes, lire la documentation et juger si l'entreprise qui l'a écrite comprenait assez bien son produit pour l'expliquer simplement, ou si la documentation ressemble à un ajout de dernière minute greffé sur une liste de fonctionnalités conçue pour une page commerciale.
Une longue liste de fonctionnalités est facile à écrire. Une documentation sur laquelle un développeur peut réellement construire du premier coup ne l'est pas, et c'est exactement pour cette différence qu'elle compte davantage.