La importancia de la documentación de las API

Dado que las API se diseñan para su consumo, es importante asegurarse de que el cliente, o consumidor, pueda implementar una API y entender qué sucede con ella rápidamente. Por desgracia, muchas API tienen una implementación extremadamente difícil, lo que desvirtúa su propio propósito. Durante el proceso de creación de una API, no solo hay que proporcionar documentación para ayudar a los desarrolladores a integrar y depurar las conexiones, también hay que asegurarse de devolver datos relevantes cuando un usuario hace una llamada, especialmente si esta da error.

Si bien es muy importante que la documentación de las API incluya una respuesta con un cuerpo coherente y un formato apropiado (pues es recomendable tener una solución que se pueda deserializar, iterar y comprender fácilmente), también hay que proporcionar a los desarrolladores referencias rápidas sobre lo que ha sucedido con la llamada, incluido el uso de los códigos de estado. Asimismo, en caso de error, hay que proporcionar mensajes de error descriptivos que indiquen al cliente no solo que algo ha ido mal, sino cómo corregirlo.

Planificar con tiempo la documentación de las API

Durante la planificación de una API, hay que planificar el mantenimiento de su documentación. No hay que subestimar la importancia de esta área, ya que ha demostrado ser la clave de la usabilidad para la mayoría de API públicas. Si bien la documentación parece una tarea rápida y fácil, la mayoría de empresas afirman que constituye uno de los mayores retos y cargas a la hora de mantener sus API.

La documentación es uno de los factores más importantes a la hora de determinar el éxito de una API. Una documentación exhaustiva y fácil de comprender simplifica mucho la implementación de APIs, mientras que una documentación confusa, desfasada, incompleta o enrevesada genera frustración en los desarrolladores y les lleva a recurrir a soluciones de la competencia.

El desafío radica en que la documentación no solo debe ser coherente en su presentación visual, sino también con la funcionalidad de las API y los últimos cambios. La documentación también debe estar redactada de manera comprensible para los desarrolladores (normalmente por un equipo de documentación experimentado). Hasta hace poco, las soluciones de documentación incluían costosos sistemas de terceros, el uso del sistema CMS (sistema de gestión de contenido) existente o incluso un CMS especial basado en software de código abierto como Drupal/Wordpress. Por desgracia, si bien las onerosas soluciones específicas para la documentación de APIs pueden aportar una apariencia homogénea a la API (algo difícil de mantener con un CMS), no por ello dejan de depender del esfuerzo manual del desarrollador (si provienen del código) o de un equipo de documentación para mantener la sincronización.

Sin embargo, gracias a la expansión de especificaciones abiertas como RAML, y las comunidades que las rodean, el proceso de documentación es ahora mucho más fácil. En lugar de preocuparse por analizar los comentarios de código e instar (normalmente) a los desarrolladores a escribir descripciones en línea, el equipo de documentación puede ofrecer una documentación descriptiva en la especificación de la API, donde ya vengan incluidos todos los parámetros y ejemplos, lo que hace que la transición a la documentación sea inmediata. Asimismo, gracias al auge de empresas del software como servicio (SaaS) de documentación de APIs, que utilizan y amplían estas especificaciones, crear un portal de APIs y documentación nunca ha sido tan fácil y barato. 

Cómo redactar una documentación de APIs de calidad

Una buena documentación debe actuar como una referencia de aprendizaje que permita a los desarrolladores obtener la información que buscan de un vistazo, así como entender cómo integrar el recurso o método que están examinando.

Por tanto, una documentación de calidad debe ser clara y concisa, pero también ilustrativa, además de proporcionar lo siguiente:

  • Una explicación clara de lo que hace el método/recurso
  • Leyendas que incluyan información importante para los desarrolladores, como advertencias y errores
  • Una llamada de muestra con el cuerpo del tipo de medio relacionado
  • Una lista de los parámetros utilizados en este recurso/método, así como sus tipos, formato especial, reglas y si son obligatorios o no
  • Una respuesta de muestra que incluya el cuerpo del tipo de medio
  • Ejemplos de código de varios lenguajes, incluido todo el código necesario
  • (p. ej., cURL con PHP, así como ejemplos de Java, .Net, Ruby, etc.)
  • Ejemplos de SDK (si se proporcionan SDK) que muestren cómo acceder al recurso/método utilizando el SDK para su lenguaje
  • Experiencias interactivas para testar llamadas de APIs (API Console, API Notebook)
  • Situaciones y preguntas frecuentes con ejemplos de código
  • Enlaces a recursos adicionales (otros ejemplos, blogs, etc.)
  • Una sección de comentarios donde los usuarios puedan hablar y compartir código
  • Otros recursos de asistencia (foros, formularios de contacto, etc.)

Herramientas de documentación de APIs

Una de las ventajas clave del desarrollo basado en especificaciones es que, en lugar de depender de proveedores costosos y complejos, o de tener que intentar crear una solución propia de documentación de APIs a partir de un sistema CMS como WordPress o Drupal, las especificaciones como RAML, Swagger y API Blueprint cuentan con grandes comunidades de código abierto que ofrecen herramientas de documentación prediseñadas que todo el mundo puede utilizar. Cada una proporciona su propio conjunto de herramientas, pero en este artículo nos centraremos en las que están disponibles en la comunidad de RAML. La comunidad de RAML ya ha creado analizadores sintácticos para diferentes lenguajes, como Java, Ruby, PHP y Node, así como scripts completos para gestionar la documentación de APIs a la par que se proporcionan entornos interactivos como API Console y API Notebook. Estas herramientas aportan documentación, tal y como se evidencia en los ejemplos anteriores de ReadMe.io, Constant Contact y Twilio, sin apenas esfuerzo por parte del usuario (más allá de la instalación y, por supuesto, la definición del lenguaje RAML). Aquí puedes encontrar varias herramientas en descarga gratuita.

Las empresas reconocen el valor creciente de las API y están empezando a desarrollar cientos de ellas. La capacidad de publicarlas de manera que el desarrollador usuario pueda encontrarlas, investigarlas y comprenderlas fácilmente será un aspecto clave para el éxito de sus programas de APIs. Una buena documentación es esencial para ello.