Hack Day Mailgun : rendre notre documentation API plus intelligente

Chaque mois, notre équipe a l’opportunité de travailler sur le projet de son choix. Une façon amusante d’apprendre quelque chose de nouveau, de collaborer avec différents membres de l’équipe ou simplement de corriger un détail agaçant.

Pour le Hack Day de janvier, quelques-uns d’entre nous (Anton, Jesse et moi-même) avons décidé d’apporter quelques améliorations à notre documentation API.

Notre API est bien documentée et dispose d’un large éventail d’exemples de code pour tous les principaux langages de programmation. Cependant, nous avons remarqué deux ou trois choses concernant le flux de travail.

Pour tester une requête API, la procédure habituelle est la suivante :

1. Copier un exemple de code dans un éditeur de texte
2. Modifier certains paramètres (par ex. l’expéditeur, les destinataires, le corps du texte)
3. Se rendre dans son panneau de contrôle Mailgun pour copier sa clé API
4. Retourner dans l’éditeur de code et coller la clé
5. Copier cet exemple dans sa ligne de commande et l’exécuter

Pour explorer rapidement un nouveau service ou tester un nouveau point de terminaison, cela semble faire un peu trop d’étapes.

Désormais, les exemples de code que nous vous présentons sont un peu plus intelligents. Si vous êtes connecté à Mailgun, nous injectons automatiquement votre clé API et certains paramètres par défaut pertinents.

Il suffit donc de copier-coller les exemples de code dans votre ligne de commande, de les exécuter, et ils devraient fonctionner du premier coup.

Nous avons également rendu les exemples de code modifiables. Avec l’ éditeur Ace, il suffit de cliquer sur n’importe quel exemple de code pour le transformer en un petit éditeur de texte intégré au navigateur, dans lequel vous pouvez effectuer des modifications.

La documentation API est essentielle à l’expérience utilisateur d’un service de développement. Avec le déploiement de ces modifications en production, nous espérons qu’il sera beaucoup plus facile de tester notre API pour les personnes qui découvrent notre service, ainsi que pour notre clientèle existante souhaitant tester ou dépanner différents points de terminaison d’API.

Découvrir les améliorations apportées à la documentation Mailgun.

Auteur·trice: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!