Mailgun Hack Day: cómo hacer más inteligente nuestra documentación de la API

Cada mes, nuestro equipo tiene la oportunidad de programar y experimentar con lo que queramos. Una forma divertida de aprender algo nuevo, colaborar con diferentes integrantes del equipo o, simplemente, arreglar algo que nos estaba molestando.

En el hack day de enero, un pequeño grupo (Anton, Jesse y yo) nos propusimos hacer algunas mejoras en nuestra documentación de la API.

Nuestra API está bien documentada y tiene una buena variedad de ejemplos de código para todos los principales lenguajes de programación. Sin embargo, nos dimos cuenta de un par de cosas sobre el flujo de trabajo.

Para probar una solicitud de la API, cualquier profesional del desarrollo normalmente tendría que:

1. Copiar un ejemplo de código en un editor de texto
2. Editar algunos parámetros (p. ej., remitente, destinatario, texto del cuerpo)
3. Ir a su panel de control de Mailgun para copiar su clave de API
4. Volver al editor de código y pegar la clave
5. Copiar el ejemplo en su línea de comandos y ejecutarlo

Para explorar rápidamente un servicio nuevo o probar un nuevo punto de conexión, parecen demasiados pasos.

Ahora los ejemplos de código que te mostramos son un poco más inteligentes. Si has iniciado sesión en Mailgun, integraremos tu clave de API y algunos valores predeterminados de forma inteligente para facilitarte las cosas.

Por lo tanto, solo es cuestión de copiar y pegar los ejemplos de código en tu línea de comandos y ejecutarlos, de forma que funcionen a la primera.

También hemos hecho que los ejemplos de código se puedan editar. Con el editor Ace, al hacer clic en cualquier ejemplo de código, este se convertirá en un pequeño editor de texto integrado en el navegador en el que podrás hacer cambios.

La documentación de la API es fundamental para la experiencia de usuario de un servicio de desarrollo. Con estos cambios implementados en producción, esperamos que probar nuestra API sea mucho más fácil tanto para quienes empiezan a explorar nuestro servicio como para los perfiles de desarrollo que ya lo usan y quieren probar o solucionar problemas de los diferentes puntos de conexión de la API.

Echa un vistazo a las mejoras en la documentación de desarrollo de Mailgun.

Autor: 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!