Tiempo de lectura: 9 minutos
Las APIs hacen que el mundo gire. Los desarrolladores utilizan las APIs casi todos los días – según algunas estimaciones, pasan la friolera de más de 10 horas a la semana trabajando con las APIs. Esto abarca no sólo su uso, sino también la investigación, la búsqueda de apoyo en Google, el estudio de las revisiones y, por supuesto, la búsqueda en la documentación. La claridad, la facilidad, la utilidad y el soporte de su API determinan toda la experiencia del desarrollador (DX), una respuesta emocional que los desarrolladores tienen hacia el producto. En la economía de las API, una gran experiencia del desarrollador es fundamental. Las APIs que ayudan a los desarrolladores a tener éxito y son un placer de usar conseguirán toneladas de usuarios y se elevarán por encima de la competencia. Y esto comienza en el momento exacto en que abren la documentación por primera vez.
Mira este vídeo para una introducción a la tecnología de las API
Hoy hablaremos de cómo fomentar la experiencia positiva de los desarrolladores en la documentación de las API. Pero primero, tenemos que entender lo que hace mala documentación de la API.
Lo que los desarrolladores odian en la documentación de la API
La comunidad de desarrolladores es apasionada. Es específicamente apasionada sobre las cosas que no les gustan. Si no les gusta una API, la mayoría de las veces es debido a la documentación basura, incluso si el producto es realmente grande. Aquí hay algunos problemas comunes que los desarrolladores tienen con los documentos de la API.
No está escrito usando un lenguaje humano simple. Este es un problema común para los docs autogenerados o los docs que son descuidados por los creadores. Aunque muchas herramientas de generación de documentación hacen un gran trabajo comentando el código, no pueden sustituir las explicaciones reales en inglés escritas por un desarrollador o escritor técnico.
Tiene muy pocos ejemplos de código. Este es otro extremo del espectro donde las explicaciones son abundantes, pero hay mínimos ejemplos del código real.
Sólo está disponible para usuarios registrados. Esta maniobra no tan hábil no hace nada para su comercialización. Sólo frustra a las personas que quieren saber lo que hace tu API antes de decidir si la quieren (como haría cualquier persona en su sano juicio).
Es demasiado larga/no se puede encontrar/es inexacta/no se ha actualizado en años, etc. Crear buenos documentos es casi tan importante como construir una buena API. Porque los documentos mal escritos o los que no se pueden encontrar simplemente buscando en Google «API de productos» son un fracaso para todo el esfuerzo de desarrollo. Si te interesa, ya hemos explicado los aspectos específicos de la documentación técnica en general. Pero la documentación de la API merece un artículo específico. Así que, ¿cómo escribir una buena documentación de la API?
Adoptar el desarrollo orientado a las especificaciones
El desarrollo orientado a las especificaciones (SDD) es similar al desarrollo orientado a las pruebas, en el que se escriben casos de prueba para cada característica y luego se escribe el código que debe pasarlas. En SDD, creas documentos o al menos algunas partes de ellos en paralelo a la construcción de una API, a menudo siguiendo un determinado formato de descripción de la API llamado especificación.
Una especificación de la API es como una plantilla de tus futuros documentos, el lenguaje unificado que describe el diseño de tu API, explica cómo funciona y qué se puede esperar de ella. Hay algunas especificaciones, como RAML (RESTful API Modeling Language), OpenAPI (antes Swagger), y API Blueprint, pero hay una tendencia a combinar todas las especificaciones bajo el capó de OpenAPI.
Estas especificaciones tienen herramientas de documentación pre-construidas que permiten escribir y gestionar sus documentos. Por ejemplo, API Console genera automáticamente documentos a partir de los formatos RAML y OpenAPI y le ayuda a ejecutarlos en su aplicación web existente o como una aplicación independiente.
API Console le permite construir un portal web para sus documentos de API a partir de las especificaciones RAML y OpenAPI
Fuente: Pawel Psztyc
Alternativa a las soluciones tradicionales de documentación de APIs como WordPress o Drupal CMSs, los productos de especificaciones de APIs son de código abierto, creados por la comunidad de desarrolladores para la comunidad de desarrolladores, tienen parsers en diferentes lenguajes de programación, y soporte constante de los creadores.
Escribir para el nivel de entrada
Hay una razón por la que la documentación técnica no suele ser escrita por los propios desarrolladores – es el trabajo de los escritores técnicos, expertos en traducir aspectos técnicos en un formato legible. Pero incluso los escritores técnicos tienden a filtrar un poco de jerga en el texto.
Una API, como cualquier producto de software, se crea para un público específico. Pero el público de la documentación es muy amplio. Hay tres grupos principales de usuarios de la documentación:
- desarrolladores que interactuarán íntimamente con la documentación
- tomadores de decisiones como directores de tecnología y arquitectos de soluciones que quieren determinar si su API será una buena opción rápidamente
- observadores como periodistas, escritores de tecnología e incluso competidores que no necesariamente utilizarán su API nunca.
Incluso dentro de cada uno de estos grupos, hay personas con diferentes habilidades, roles y necesidades, y todos ellos deberían tener una experiencia positiva con los documentos. ¿Cómo se puede llegar a todos ellos? Dirigiéndose a los usuarios menos experimentados. Entonces, ¿cómo se escriben los documentos para un recién llegado?
Empiece por las oportunidades más que por los tecnicismos. Reciba a los usuarios con una historia convincente que explique cómo su API puede enriquecer su producto o facilitar la vida de los desarrolladores.
Los documentos de la API de Amazon Alexa comienzan explicando qué hace Alexa y qué beneficio puede aportar al cliente
Muestre por dónde empezar. Los docs de la API son notorios por ser demasiado abrumadores y asumir que los usuarios tienen una vasta experiencia con las APIs. La sección de introducción es obligatoria, y debe estar escrita con paciencia para un usuario potencial.
Facebook proporciona una referencia clara para los principiantes y sigue el proceso de introducción paso a paso
Crea instrucciones para los casos de uso más comunes. Probablemente ya sepas para qué funciones utiliza la gente tu API. Cree secciones separadas que se dirijan a ellas e incluya allí mensajes de ejemplo.
Use un tono conversacional. La comunidad de desarrolladores es relajada e informal, por lo que no apreciarán un lenguaje corporativo seco aunque suene más «profesional». Los buenos documentos siempre se dirigen a los humanos.
Infórmese sobre las herramientas externas. Si su API requiere el uso y la comprensión de productos y conceptos de terceros como OAuth o npm, incluya enlaces a documentos o guías de instalación.
Haga que sea fácil de aprender. Los documentos de la API no son instrucciones de montaje de IKEA, sino que son la fuente de aprendizaje. Enriquece tu documentación con preguntas frecuentes, tutoriales, blogs e incluso vídeos cuando sea posible.
Incorpora secciones imprescindibles
En 2019, SmartBear, el desarrollador de Swagger, encuestó a desarrolladores y usuarios de API. Encontraron qué características de docs son consideradas las más importantes en la comunidad, dándonos una lista de las secciones de documentación imprescindibles que los devs quieren cubrir. Vamos a repasar algunas de ellas.
SmartBear encuestó a 3.000 profesionales de las API
Ejemplos. Los ejemplos suelen presentarse como trozos de código, que son suficientemente útiles pero que pueden hacerse aún más prácticos. Por ejemplo, incluyendo una transcripción de campos como se hace en los docs de Medium o incluso creando una API simulada para que los desarrolladores la prueben y la utilicen haciendo llamadas reales. Las APIs simuladas se pueden compartir fácilmente a través de una URL o en GitHub, y si se hace con cierto nivel de detalle, incluso se pueden utilizar en el producto final.
Estado y errores. Hay códigos de estado estándar y los específicos de tu API. Es una buena idea incluir todos los errores que pueden ser desencadenados por su API. Los errores a menudo se ponen en una página dedicada de los documentos, pero tiene sentido para duplicar algunos de ellos directamente bajo el punto final en el que la superficie más.
Autenticación. La mayoría de los documentos de la API comienzan con la autenticación y la autorización. Debería cubrir información sobre cómo obtener una clave de API y cómo autenticar solicitudes, incluyendo posibles errores, tiempos de expiración de tokens, y una explicación sobre la sensibilidad de la autenticación (básicamente recordando que las claves no pueden ser compartidas, y dónde pueden ser utilizadas).
Solicitudes HTTP. Proporcionar peticiones web en HTTP es lo mínimo para la documentación. Normalmente se asume que los desarrolladores sabrán cómo enviar peticiones HTTP en su idioma de elección, pero a veces, los creadores de la API incluyen peticiones en varios idiomas. Esto se puede hacer automáticamente a través de las herramientas de especificaciones de la API y las herramientas de gestión de la API como Postman.
Usa el diseño estándar de la industria
Si estás usando un generador de documentación, el diseño ya está decidido por ti. La mayoría de los documentos de la API tienen el mismo aspecto. Si has utilizado algunas, ya sabes cómo enfocar los nuevos documentos. Aun así, organizar grandes volúmenes de datos, hacerlos localizables y facilitar la navegación es una tarea compleja. Estas son algunas de las características de la disposición más funcional.
Disposición dinámica. Se puede reconocer una API obsoleta por su documentación estática. Una sola página o incluso un documento PDF no es suficiente en 2020. Los documentos dinámicos son fáciles de consultar, actualizar y marcar como favoritos.
Contenidos pegajosos. No, la barra de navegación no distrae ni roba el precioso espacio de la pantalla. Siempre mantiene los contenidos a la vista.
Disposición de tres columnas. No se utiliza muy a menudo, este diseño le permite tener otra columna a la derecha para los ejemplos de código. Por supuesto, esto sólo tiene sentido si tienes una tonelada de texto y quieres resaltar el código para que los usuarios no tengan que desplazarse hacia adelante y hacia atrás o cambiar entre pestañas.
Los documentos de la API de HubSpot utilizan un diseño de tres columnas
Usa colores de contraste para la sintaxis. Los desarrolladores pasan mucho tiempo mirando tus ejemplos de código, así que hazlos legibles y separa los diferentes componentes por colores.
Este ejemplo de los docs de la Graph API de Facebook también muestra cómo puedes usar diferentes pestañas para elegir entre SDKs
Guarda el estado del scroll. Este es un pequeño detalle que cualquier desarrollador agradecerá. También puedes utilizar enlaces de anclaje para especificar diferentes secciones de la página en caso de que copien la URL.
Fomenta los comentarios. Tus documentos son tu principal herramienta de marketing: si a la gente le gustan, utilizarán tu API por encima de las de la competencia e impulsarán la comunidad en torno a ella. El habitual mensaje «¿Le ha resultado útil esta página?» le permitirá saber lo bien que está respondiendo a las preguntas de los desarrolladores y el formulario de comentarios se utilizará a menudo siempre que lo cumpla.
No abandone sus documentos
Los documentos obsoletos son la mayor manía de los usuarios de API. También es uno de los errores más comunes. Los desarrolladores suelen escribir sobre las actualizaciones varios días después de lanzarlas, a veces limitándose a unas pocas frases. Esto sucede porque no hay un proceso establecido para las actualizaciones de los documentos y no es responsabilidad de nadie. He aquí cómo asegurar actualizaciones regulares y útiles de los documentos.
Prepare los documentos antes de las actualizaciones. Hágalo un paso adicional en su plan de lanzamiento, no los lance antes de tener párrafos bien escritos, detallados y editados para introducir sus actualizaciones.
Retire regularmente los datos obsoletos. Los documentos deben ser revisados con frecuencia, al menos una vez cada pocos meses. Las funciones de retroalimentación de los usuarios le permitirán detectar antes las incoherencias y siempre debería haber un miembro del equipo responsable de revisarlas y reaccionar ante las actualizaciones.
Utilice los análisis para mejorar los documentos. Las analíticas estándar de la API le dirán qué puntos finales se utilizan con más frecuencia, de modo que puede centrarse en ciertas partes de la documentación y proporcionar información más útil o crear tutoriales dedicados. Monitoriza los casos de uso de tus APIs porque eso te permitirá ampliar la propuesta de valor y actualizar la documentación con más posibilidades.
Grandes ejemplos de documentación de APIs
Hay toneladas de buena documentación para explorar y aprender de ella. Además de los ejemplos que hemos compartido a lo largo del artículo, aquí hay algunos más para que los disfrutes y tomes nota.
Documentación de la API de Medium
Los documentos de la API de Medium no necesariamente cumplen con todas las reglas que hemos enumerado hoy, pero son excelentes para la funcionalidad limitada que soporta esta API: publicar y buscar publicaciones en Medium. Se comparten en GitHub, tienen un contenido realmente corto pero claro con toneladas de ejemplos, y cada uno termina con una transcripción de todos los parámetros mencionados en el código, incluidos los posibles errores. Es notablemente sencillo, pero fiable: todas las sugerencias se pueden hacer directamente en GitHub y los docs se actualizan regularmente.
Documentación de la API de Mailchimp
Mailchimp es consciente de que la mayor parte de su público son profesionales del marketing y utiliza un lenguaje que permite incluso a personas no tecnológicas entender cómo trabajar con sus APIs. A simple vista, cada sección sigue la misma estructura:
- lo que hace un endpoint y lo que la guía permitirá hacer a los usuarios
- lo que necesitará – cualquier acceso o cuenta que un usuario deba obtener primero
- lo que es cada función con una descripción de texto, un ejemplo de código en varios idiomas y, a veces, capturas de pantalla de la interfaz.
Incluso hay un botón de copia para cada pieza de código – un detalle que los que no son técnicos sin duda apreciarán.
Documentación de la API de Twilio
Twilio tiene docs famosos de la API. Aunque los docs son sólo la punta del iceberg de toda la ayuda que Twilio comparte – hay SDKs en varios idiomas y aplicaciones de ejemplo para iOS, Android y web. En primer lugar, siguen la lógica de tres columnas con el código directamente a la derecha de la guía. Las acciones más sencillas se explican con detalle y un montón de enlaces para obtener información adicional y capturas de pantalla. También se fomentan los comentarios a través de un botón «Valora esta página» y enlaces al equipo de soporte y a la etiqueta en StackOverflow.
Documentación de la API de Spotify
Aunque los documentos de la API web de Spotify son muy típicos, tienen mucha información adicional en su plataforma Spotify for Developers. Hay demos de funciones básicas, aplicaciones simuladas, ejemplos en vivo construidos con APIs y widgets de Spotify, wrappers para diferentes lenguajes de programación y, por supuesto, la consola. La consola es básicamente una documentación interactiva en la que puedes introducir tus datos (o muestras) y explorar los puntos finales en directo. Los potentes productos junto con una sólida base de conocimientos hacen de Spotify un socio fiable con el que a los desarrolladores les gusta trabajar.
Trata la documentación con cuidado
La documentación es el único punto de contacto que tendrás con la mayor parte de tu audiencia, así que tienes que aprender a comunicarte con claridad a través de ella. El mejor consejo aquí es hacer que sea el trabajo de alguien. A menudo, se trata de un redactor técnico que sabe cómo dirigirse a públicos de diferentes habilidades, que puede traducir las palabras de los desarrolladores en puntos procesables, que supervisa el mantenimiento y la actualización oportunos de los documentos. Pero la gestión de una gran documentación es posible incluso sin un experto en su plantilla. Las herramientas de gestión de API como Swagger UI, Spotlight, Apiary y las herramientas de especificación de documentos tienen una amplia funcionalidad para ayudarle a crear documentos que los desarrolladores amarán.