5 points à corriger dans la documentation de votre API

Tout adulte le reconnaît en un clin d'œil grâce à la forme et à la couleur d'une bouteille de bière. C'est le temps dont un développeur expérimenté a besoin pour décider si la documentation de votre API en vaut la peine. Est-ce suffisamment technique ? S'agit-il même d'une documentation d'API ou d'une page de vente ? Clignez des yeux. Passez à autre chose.

Ce processus de réflexion et cette reconnaissance instantanée font partie de l'expérience des développeurs, un terme souvent (mal) utilisé. Une seule API ou un kit de développement logiciel (SDK) peut créer une bonne ou une mauvaise expérience pour les développeurs. Lorsque nous parlons de l'intégration des développeurs en tant que nouveaux consommateurs d'API, nous devons tenir compte de l'expérience client et utilisateur de ces développeurs. Cela est souvent inclus dans le terme « expérience du développeur » lorsqu'on parle d'API.

• Quelles sont leurs attentes quant au fonctionnement des API ?
• Comment accèdent-ils à l'API ?
• Devraient-ils payer pour l'API ou l'obtenir gratuitement, du moins pour l'essayer ?
• À quels types d'exemples, de documentation, de mise en page et de contenu attendent-ils, et sur quels canaux s'attendent-ils à trouver votre API ?

Même les développeurs ne constituent pas un groupe identique. Leurs attentes varient en fonction de qui ils sont. Junior contre senior, front-end contre backend contre langages d'intégration et de programmation et outils qu'ils utilisent. Et bien entendu, les développeurs ne sont pas le seul groupe d'utilisateurs dont vous avez besoin pour parler de votre API ou de votre SDK.

‍

‍ Les points de contact préalables à l'achat permettent au développeur de comprendre qu'il a un besoin spécifique. Cela peut être quelque chose de fonctionnel, comme la reconnaissance faciale ou le calcul des frais d'expédition. Il peut également s'agir d'accéder à des données telles que la cartographie des adresses postales avec les codes postaux. Le développeur commence alors à rechercher des solutions internes ou externes.

N'oubliez pas qu'elle a toujours la possibilité de mettre en œuvre elle-même la fonctionnalité nécessaire. Comme dans tout parcours client, ce qu'il faut comprendre, c'est l'impact de l'expérience précédente du client développeur. Cela peut inclure une expérience de l'utilisation d'autres API ou d'autres services. Ces expériences passées affecteront la façon dont ils perçoivent vos API.

Lorsque la développeuse avance dans son parcours, elle a besoin d'un moyen de tester l'API. Avec les API, comme tout produit logiciel, il est essentiel de les essayer avant d'acheter. Réduisez le nombre de questions au strict minimum avant qu'ils puissent essayer au moins un ensemble minimal de fonctionnalités avec l'API.

Les points de contact après l'achat sont essentiels, comme l'obtention d'une assistance et la promotion de l'API. Découvrez les canaux et les moyens permettant aux développeurs d'obtenir de l'aide à l'aide de l'API. Peu importe ce que vous déciderez de leur proposer en tant que canaux d'assistance, ils chercheront peut-être de l'aide ailleurs. Le développeur fait peut-être des recherches sur le Web ou écoute ses YouTubers préférés. Elle peut poser une question à ses pairs dans Stackoverflow, Gitter, Reddit ou Discord.

Si tout se termine bien et que le développeur résout son problème de codage à l'aide de votre API, il se peut qu'il soit votre meilleur défenseur. Ils peuvent même créer des didacticiels, des vidéos, des bibliothèques de code utiles ou utiliser votre API pour former d'autres personnes. Ils peuvent répondre aux questions d'autres développeurs concernant votre API sur certains forums d'assistance de la communauté et réduire ainsi votre charge de support.

Passons aux 5 éléments que vous devez modifier dans votre documentation :

1. À quoi sert votre API ?

Cela devrait être évident dès le premier titre et la première phrase de la documentation de votre API. Et pour chaque point final. Assurez-vous qu'il est écrit pour votre public cible. Le pire que j'ai vu est « API de recherche : l'API de recherche est utilisée pour effectuer des recherches ». Ok, mais pour chercher quoi ? Pourquoi ? Existe-t-il des limites ou des combinaisons spéciales ? S'il s'agit d'une API dans un portail de développement contenant des API publiques, partenaires et privées, à qui s'adresse cette API ? Ou pourriez-vous l'ouvrir à tout le monde ? C'est une chose à laquelle vous devez déjà penser lors de la conception de l'API.

C'est également le point de départ de la méthode APIOps Cycles sous licence creative-commons pour le développement d'API. Tout commence par la proposition de valeur de l'API.

2. Arrêtez-vous avec les diagrammes de séquence, expliquez votre produit

Pensez-vous que les développeurs savent ce que fait votre produit ou service actuel par rapport à ce pour quoi ils utilisent l'API ? Votre produit ou service peut nécessiter des connaissances spécifiques. Comme un logiciel de comptabilité, un service de paiement ou un service de transcription. Si vous ne comprenez pas comment cela fonctionne, il n'est guère possible de comprendre ce que fait l'API.

Vous pourriez être tenté de mettre des organigrammes ou des diagrammes de séquence dans la documentation de votre API. Cela se produit généralement si quelqu'un a créé des diagrammes lors du développement de l'API. Parce qu'une image vaut mieux que mille mots, non ?

Faux.

Ces diagrammes qui sont souvent dessinés d'un point de vue interne. Et il leur manque le flux d'utilisateurs de votre produit. Si vous disposez de 10 points de terminaison différents pour votre API, le développeur externe aura probablement besoin d'un diagramme de processus. Il doit montrer le flux typique d'utilisation de votre produit ou d'accomplissement d'une tâche spécifique dans le produit. En prime, quels sont les points finaux nécessaires. Clarifiez cela en 1 à 5 points simples sous forme de liste. Si vous ne le pouvez pas, envisagez peut-être de simplifier le produit lui-même ?

3. Moins de mots, une meilleure API

Maintenant, sortez un ruban à mesurer. Copiez au moins votre texte dans Word ou dans un autre processeur qui vous indique le nombre de mots de la documentation de votre API. Si vous avez plus de 300 mots de prose, soyez un peu inquiet. Regarde ton texte. Est-ce quelque chose comme ceci : « Vous devez utiliser des connexions sécurisées lorsque vous appelez notre API... » ?

Si vous devez écrire tout cela en phrases, c'est un signe que vous devrez peut-être rediriger.

1) vous avez engagé un rédacteur technique « non-API » pour rédiger la documentation de votre API., ou

2) Les utilisateurs de votre API rencontrent les mêmes problèmes ou vous posent des problèmes. Ce que vous devez faire, c'est corriger l'API ou utiliser la gestion des API (voir point suivant).‍

4. S'il vous plaît, gentil Monsieur, ne bloquez pas mon API

Arrêtez de plaider : « Veuillez ne pas passer trop d'appels vers notre API, du moins pas pendant les heures de bureau ». Si quelqu'un peut bloquer votre API en effectuant ses appels quand il le souhaite, il le fera. Pas parce qu'ils ne sont pas très sympathiques. Parce que quelqu'un fait une erreur de codage quelque part et envoie du spam à votre API par accident. Une fois, une dame âgée a posé sa tasse de café sur le dessus du clavier. Elle a réussi à faire planter toute une application SaaS avec cette application en passant trop d'appels. Des personnes mal intentionnées essaieront de bloquer votre API. Ce que vous dites, c'est que rien ne les empêche, du moins de ralentir votre application.

Un conseil essentiel : fixez au moins une limite de débit maximale stricte à votre API (par minute et par utilisateur) et un message d'erreur standard intelligent.

‍

5. Validez votre schéma, dans son intégralité

Si vous concevez et publiez vos API avec OpenAPI, et vous devriez le faire, assurez-vous de valider à la fois le JSON, le XML ou le YAML, mais surtout, validez également le fichier de définition OpenAPI lui-même. Et tes exemples. Les développeurs ne peuvent pas utiliser d'outils ou de bibliothèques directement pour utiliser l'API, si celle-ci n'est pas valide.

Ok, ce n'étaient que les 5 meilleures choses. En général, nous passons jusqu'à 20 articles dans notre liste pour consulter votre API et votre documentation.