Les constructeurs d’API doivent vendre aux développeurs ou mourir lentement

Dans le passé, la convivialité pour les développeurs était rarement prise en compte lorsqu’il s’agissait d’intégrations d’API. Publier une référence Swagger (maintenant connue sous le nom d’OpenAPI) était souvent ce qu’une entreprise pouvait et voulait faire pour ses utilisateurs développeurs. Après cela, vous étiez seul. J’espère qu’armé de quelques boissons fraîches, vous pourrez sortir de ces bois.

Mais aujourd’hui, les produits conviviaux pour les développeurs gagnent rapidement un avantage sur le marché. Tout outil qui rend un produit plus accessible aux développeurs peut améliorer les résultats d’une entreprise. C’est pourquoi les entreprises qui réussissent font de grands efforts pour trouver et fournir ces outils.

Nous approchons rapidement d’un point d’inflexion. Les entreprises disposent de plus d’options d’outils que jamais pour offrir aux développeurs une expérience exceptionnelle. Cela a conduit à une recrudescence du nombre d’entreprises en concurrence avec les plateformes établies, et l’amélioration de l’expérience des développeurs constitue le principal différenciateur concurrentiel. Par exemple:

• Le renvoi s’en prend à Mailchimp.
• PostHog s’en prend à Google Analytics, Amplitude et LaunchDarkly.
• Airbyte s’en prend à Fivetran.
• Dub.Co s’en prend à Bit.ly.
• Hex s’en prend à Jupyter.

La liste est longue et votre entreprise y figure peut-être.

La raison en est que trop de plates-formes API n’ont jamais été conçues en pensant aux développeurs. Les API ont simplement été intégrées au hasard aux produits Software as a Service (SaaS) existants, sans trop se soucier de l’expérience utilisateur.

Alors pourquoi devriez-vous vous en soucier ?

Il existe de nombreuses raisons pour lesquelles l’expérience des développeurs doit être prise en compte pour les outils utilisés par les développeurs.

Une intégration plus rapide débloque les revenus des API externes

Le temps nécessaire à la mise en ligne d’une intégration se mesure en semaines, voire en mois. Lorsque les développeurs doivent se battre avec des processus alambiqués, écrire du code à partir de zéro, gérer plusieurs erreurs, etc., cela allonge les cycles de vente et diminue la croissance du chiffre d’affaires.

Les API internes affectent la productivité des développeurs

La productivité des développeurs est un KPI crucial pour la plupart des entreprises. Selon le rapport 2023 sur l’état des API de Postman, plus de 55 % des ingénieurs passent 10 heures ou plus par semaine à travailler avec des API. Le rendement des développeurs s’améliorera si vos API internes ne constituent pas des obstacles pour votre équipe d’ingénierie. En gardant vos développeurs satisfaits de leur travail, vous améliorerez la qualité de votre produit et les résultats de l’entreprise.

Les développeurs ont beaucoup de pouvoir dans les décisions d’achat

Le temps et la productivité des développeurs étant si précieux, ils ont souvent une grande influence sur les décisions des fournisseurs. Ils auront fréquemment un droit de veto s’ils doivent être des utilisateurs principaux ou même secondaires. Et il s’agit d’un public très particulier : votre présentation de vente ou votre démo mise en scène ne fonctionnera pas. Ils demanderont l’accès à votre plateforme. Si votre produit ne parvient pas à impressionner, votre accord échouera probablement.

L’IA pourrait ne pas aimer votre plate-forme SaaS

L’IA est l’utilisateur le plus récent que votre produit doit prendre en charge. Avec la lourde mise en garde que nous n’en sommes qu’à ses débuts, l’IA fonctionne mieux via les API. Des informations incorrectes, l’imprévisibilité et des interfaces peu conviviales réduisent la capacité de l’IA à utiliser les capacités de votre plateforme.

La concurrence est plus forte

Il existe une explosion d’outils disponibles pour aider les développeurs à faire leur travail mieux et plus efficacement. À l’époque, les entreprises pouvaient s’en sortir avec leur spécification Swagger parce qu’elles ne pouvaient pas faire grand-chose d’autre. À moins que vous ne soyez Stripe, avec une armée d’ingénieurs à votre disposition, vous deviez concocter des outils open source assez médiocres et écrire des flux de travail personnalisés juste pour créer quelque chose de passable. Cependant, au cours des deux dernières années, une révolution a supprimé toutes les excuses pour ne pas contribuer à la productivité des développeurs, de votre côté comme de celui de vos partenaires ou clients.

Pourquoi les entreprises restent-elles bloquées ?

Les entreprises se concentrent souvent sur le développement d’un système pour créer une documentation à jour. Ceci est souvent considéré comme le summum de l’expérience du développeur – et c’est souvent une erreur. S’il est certainement important de gérer votre documentation à l’aide d’un flux de travail bien défini et reproductible, qu’en est-il du contenu réel des documents ?

Fournir un extrait de code concis répliquant une intégration est la documentation la plus utile que vous puissiez fournir aux utilisateurs qui tentent d’intégrer votre API. Pour généraliser, si votre public cible est constitué de développeurs, alors le cœur de votre documentation doit être basé sur du code.

Vous vous félicitez peut-être maintenant en pensant : « Eh bien, nous avons des extraits de code dans notre documentation API ; nous sommes déjà les meilleurs de notre catégorie. Mais pas si vite. Le code est très important, et c’est là que la plupart des organisations échouent.

Regardez le code dans votre documentation. Est-ce que ça ressemble à ça?

Ou est-ce que ça ressemble à ça ?

Ces blocs de code vous montrent comment écrire du Python pour récupérer une ressource client à partir d’une API de facturation, mais ils ne sont pas identiques. Le premier bloc de code est un code générique qui n’aidera pas les utilisateurs à configurer une intégration de production avec l’API. C’est juste un thème Python curl demande. Les consommateurs de votre API ne l’utiliseront pas pour créer une intégration d’entreprise.

Pendant ce temps, le deuxième bloc de code correspond exactement à la manière dont un utilisateur s’intégrerait à une API en production. Il utilise le kit de développement logiciel (SDK) Python du fournisseur d’API. Même dans ce simple GET demande, les pièces de rechange du SDK doivent analyser des détails tels que la structure URL de votre API. Dès le départ, il peut gérer des problèmes importants, tels que la gestion des erreurs, la sécurité, les tentatives, la pagination et bien plus encore — tout ce dont l’utilisateur a besoin pour intégrer votre API.

Qu’est-ce qu’un SDK ?

Pourquoi les SDK sont-ils si importants pour garantir que votre produit est adapté aux développeurs ?

Tout se résume à aider vos consommateurs d’API à s’intégrer plus rapidement. Lorsque les gens décident d’intégrer votre API, ils ont un travail qu’ils veulent accomplir. Ils pensent que votre API pourrait être le moyen le plus rapide de résoudre ce problème. Mais trop souvent, construire une intégration avec l’API est aussi pénible (voire plus pénible) que le travail initial. C’est contre-productif, c’est un euphémisme. Il y a une centaine de choses que vos utilisateurs préféreraient faire plutôt que de lire la documentation de votre API et d’écrire du code d’intégration de base. Moins vous en exigerez, plus ils seront heureux. Et les SDK sont le meilleur outil pour garantir que votre API reste discrète.

La définition d’un SDK est simple : il s’agit d’une bibliothèque qui entoure votre API et gère les parties ennuyeuses du processus d’intégration, telles que :

• Construire une requête HTTP
• Gestion d’un jeton d’authentification
• Gestion des tentatives
• Analyser les réponses paginées

Des SDK plus puissants iront au-delà des bases de la gestion des requêtes et des réponses et fourniront une sécurité de type et des conseils dans l’environnement de développement intégré (IDE). Cela signifie que les utilisateurs n’ont pas besoin d’ouvrir une page de documentation ; ils obtiendront toutes les informations et les commentaires dont ils ont besoin directement dans leur environnement de codage. Il n’y a pas plus efficace que cela.

Comment créer des SDK ?

Si les SDK sont si performants, pourquoi toutes les entreprises n’en disposent-elles pas ? C’est en grande partie parce que les outils font défaut depuis longtemps : si vous vouliez un SDK, vous deviez le créer à la main, ce qui coûte beaucoup de temps et d’argent.

Les bases d’utilisateurs de la plupart des entreprises sont réparties dans différents langages et environnements d’exécution. Vous pourrez peut-être gérer un SDK à la main, peut-être même deux. Mais à terme, la charge de maintenance commence à peser sur la vitesse de développement des API, car chaque changement nécessite des mises à jour de tous les SDK. C’est pourquoi seules les plus grandes entreprises technologiques comme Stripe et Twilio étaient capables d’exécuter efficacement des programmes SDK.

Heureusement, la situation s’est considérablement améliorée ces dernières années. Il existe désormais plusieurs générateurs capables de créer des SDK à partir d’une spécification OpenAPI. Speakeasy en est un, et des outils open source sont également disponibles. Cet outil a démocratisé la création de SDK, permettant de créer un programme robuste sans un énorme engagement d’ingénierie. Tout ce dont vous avez besoin est une spécification OpenAPI à jour.

Comment obtenir une spécification OpenAPI ?

OpenAPI (anciennement connu sous le nom de Swagger) est le langage de spécification standard de l’industrie pour décrire les API REST. Il est destiné à permettre aux humains et aux outils d’analyser facilement et rapidement votre API. Cependant, il n’est pas censé être facile à écrire.

Si vous devez créer une nouvelle spécification OpenAPI, vous devrez décider si vous souhaitez la gérer manuellement ou la générer à partir du code. Il s’agit d’un sujet controversé que vous devrez évaluer et décider par vous-même. Quelle que soit l’approche que vous choisissez, la documentation Speakeasy fournit des conseils sur l’optimisation de vos spécifications pour une génération de code propre.

Que faites-vous avec vos SDK ?

Une fois que vous disposez d’une spécification OpenAPI, de SDK et d’une documentation, vous êtes prêt à tout rassembler pour créer une expérience de développement cohérente. Cela nous ramène au début : intégrer votre SDK dans votre documentation :

La plupart des plateformes de documentation devraient fournir un moyen de remplacer leurs extraits génériques par un code personnalisé exploitant votre SDK. Si vos SDK sont fabriqués à la main, vous devrez penser à mettre à jour les extraits à mesure que votre API change. C’est pénible, mais cela en vaut la peine, car cela rendra votre documentation beaucoup plus puissante et conviviale. Vous pouvez également essayer Speakeasy pour générer automatiquement des extraits de code pour vos documents.

Les extraits d’utilisation qui correspondent étroitement à l’utilisation en production sont très efficaces. Personne ne veut analyser des paragraphes de texte expliquant votre API. Les utilisateurs souhaitent copier et coller un bloc de code dans leur application, vérifier qu’il fonctionne, puis l’adapter à leur cas d’utilisation immédiat. Aucune explication n’est nécessaire.

L’effort en vaut-il la peine ?

L’intégration de production avec une API d’entreprise implique bien plus que la simple exécution d’une requête HTTP. La gestion des erreurs d’authentification, l’analyse de la pagination, les nouvelles tentatives de requête et bien plus encore doivent être prises en compte. Le statu quo pour les entreprises traditionnelles consiste à faire porter ce fardeau aux utilisateurs d’API en leur demandant d’écrire chaque intégration à partir de zéro, ce qui compromet le succès de l’API.

Les producteurs d’API peuvent rivaliser beaucoup plus efficacement en proposant des SDK qui offrent à leurs consommateurs d’API un chemin d’intégration beaucoup plus rapide et plus simple. Si des SDK sont mis en place et intégrés à vos documents, vous serez plus avancé que 90 % des entreprises du marché.

Investir dans des outils et services de développement ne consiste pas seulement à répondre à une demande ; il s’agit de pérenniser votre entreprise et de la positionner pour un succès à long terme dans un paysage technologique en constante évolution. Donc, si vous ne l’avez pas déjà fait, le moment est venu de réfléchir à ce que votre plate-forme ou service peut faire pour les développeurs et de récolter les fruits qu’ils peuvent apporter aux résultats et aux résultats de votre entreprise.