Je rédigerai une documentation API claire que vos développeurs pourront suivre dès le premier jour

Pourquoi la plupart des documentations API échouent

Elles décrivent les points de terminaison et omettent les parties qui bloquent réellement les gens: comment s'authentifier, à quoi ressemble une requête réaliste, ce que signifie l'erreur et ce qu'il faut faire à ce sujet. Le lecteur ouvre alors un ticket de support, ce qui est le coût que la documentation est censée éliminer.

Comment je l'écris

À partir de la source, pas de mémoire. Je lis les routes, la couche de validation et les gestionnaires d'erreurs, puis j'appelle l'API moi-même avec de vraies informations d'identification. Chaque exemple de la documentation est une requête que j'ai faite et une réponse que j'ai reçue — pas de charges utiles inventées, pas de codes d'état que le point de terminaison ne renvoie jamais.

Ce que contient la documentation

• Authentification: obtention d'un jeton, son rafraîchissement et ce qui se passe lorsqu'il expire en cours de session.
• Chaque point de terminaison avec ses paramètres, un exemple de requête complet et la forme réelle de la réponse.
• Une référence d'erreurs qui mappe chaque code d'erreur à une cause et une solution, plutôt que de simplement répéter le message.
• Un chemin de démarrage qui permet à un nouveau développeur de passer de zéro à un appel réussi en moins de dix minutes.
• Limites de débit, pagination, webhooks et idempotence expliqués là où ils s'appliquent réellement.

Format

Markdown dans votre dépôt, structuré pour OpenAPI ou un site de documentation — celui que vous maintiendrez réellement. Des exemples de code dans les langages que vos utilisateurs demandent, vérifiés en les exécutant. Collection Postman ou similaire incluse si vous en voulez une.

Ce dont j'ai besoin

Accès au dépôt ou au fichier OpenAPI, une information d'identification fonctionnelle pour un environnement de test, et toutes les questions auxquelles votre équipe de support est fatiguée de répondre. Ces questions constituent le plan.

Non inclus

Texte marketing. Ceci documente précisément ce que fait le logiciel; la page de destination est un métier différent.

Délai et communication

Une première ébauche complète arrive généralement dans la semaine, et vous la révisez en fonction des questions auxquelles votre propre équipe de support continue de répondre. Je préfère être corrigé tôt par l'ingénieur qui connaît les cas limites plutôt que de livrer quelque chose de poli et d'erroné. Chaque exemple du document final a été exécuté sur votre API, donc rien n'est aspirationnel.