Documentación de API: Cómo escribirlo y ejemplos

¿Qué es la documentación API?

La documentación de la API es un conjunto de instrucciones que le dice a los desarrolladores y a otras partes interesadas cómo utilizar su API y sus servicios para un fin específico. Normalmente contiene ejemplos de código, tutoriales y detalles sobre las funciones, clases y tipos de retorno. Básicamente proporciona a los desarrolladores toda la información que necesitan para construir integraciones con la API y hacer llamadas API con el software.

Las llamadas API son un tipo de petición que hace el desarrollador de terceros a la API de la plataforma. Las llamadas API se describen en la documentación y le dicen al desarrollador exactamente qué pueden pedir a la API que haga y cómo.

La documentación de la API explica claramente sus extremos, interpreta por qué quieres usarlos y da ejemplos muy específicos de cómo quieres usarlos.

Las APIs son importantes porque significa que los desarrolladores no tienen que seguir construyendo las mismas soluciones de software una y otra vez desde cero. APIs significa que los desarrolladores pueden aprovechar otras plataformas que ya han sido creadas e integrar su funcionalidad en sus propios programas. Muchas grandes plataformas tienen APIs, incluyendo Twitter y GitHub.

Tipos de API

Para el equipo

Usted puede tener una API que sea interna a su empresa y por lo tanto destinada a ser utilizada únicamente por miembros de su equipo. El propósito de este tipo de API sería agilizar la transferencia de datos entre equipos y sistemas, para que los desarrolladores internos de su empresa sean los encargados de usar esta API.

Para los socios

Las APIs asociadas se comparten fuera de la organización, pero sólo con aquellos que tienen una relación de negocios con la empresa que proporciona la API. Sólo los clientes autorizados tienen acceso a la API y, como consecuencia, las medidas de seguridad tienden a ser más estrictas con este tipo de API.

Para los usuarios finales

APIs para usuarios finales o APIs abiertas pueden ser utilizadas por cualquier desarrollador sin restricciones. Este tipo de APIs no tienen medidas de autenticación y autorización especialmente estrictas porque los proveedores quieren que la API sea adoptada por tantos desarrolladores como sea posible. A veces este tipo de API estará disponible por una cuota de suscripción que es escalada dependiendo del número de llamadas de la API que se estén realizando.

¿Quién escribe la documentación API?

Naturalmente, como desarrolladores son los que construyen las APIs a menudo tienen la tarea de escribir la documentación. Desafortunadamente, la documentación impulsada por el desarrollador a menudo puede ser demasiado técnica porque los desarrolladores están tan cerca del tema. La documentación escrita por los desarrolladores también puede caer en el camino, ya que los desarrolladores están realmente enfocados en construir y mantener la API.

Por esta razón, muchas empresas emplean a escritores técnicos profesionales para crear su documentación API. Los escritores técnicos tienen la capacidad técnica de entender la API y las habilidades creativas para poder escribir contenido atractivo para los usuarios finales que son desarrolladores.

Los desarrolladores de la API proporcionan al escritor técnico la información que necesitan para poder documentar la API con exactitud. Si faltan partes en la documentación, los desarrolladores pueden ayudar al escritor técnico a rellenarlas, con el resultado final de tener un documento claro y accesible para su público objetivo.

También, revisa nuestro artículo en Cómo crear una experiencia encantadora de desarrollador API con la documentación

Beneficios de la documentación de API

Para los proveedores que quieren ofrecer una API, desarrollar documentación puede tener muchos beneficios importantes para su organización.

Mejora la experiencia del desarrollador de API

En primer lugar, la documentación de API mejora la experiencia del desarrollador. No importa lo bueno que sea tu API si los desarrolladores potenciales no entienden cómo usarla. Una buena documentación de API ayuda a los desarrolladores a entender los diferentes puntos finales que tiene para ofrecer y ejemplos de casos de uso particulares. Cuando mejoras la experiencia del desarrollador incrementas el número de usuarios potenciales que puedes atraer a tu producto.

Reduce el tiempo de uso interno de desarrolladores internos o socios externos
Una buena documentación API significa que tus equipos de apoyo y éxito necesitan pasar menos tiempo incorporando nuevos desarrolladores internos o socios externos. Los nuevos usuarios de su API tienen toda la información que necesitan para empezar con su plataforma y configurarse para el éxito. Cuando los procesos están documentados, elimina la necesidad de que determinados miembros del equipo intervengan.

Mantenimiento de producto eficiente y actualizaciones más rápidas

Cuando documentas tu API de forma efectiva, significa que puedes administrar el mantenimiento de tu producto y actualizarlo más rápidamente. Con la documentación API usted sabe exactamente qué debe hacer su producto y cómo debe ayudar a los usuarios finales. La documentación le da una visión más íntima de la API y le permite desplegar actualizaciones más rápidas que serán adoptadas por los usuarios.

Ayuda tanto a los usuarios internos como externos en la integración de la API y sus capacidades

Uno de los principales beneficios de documentación de la API es que ayuda a los usuarios internos y externos a entender la API, para qué se puede usar, y cómo se puede desplegar la API para sus propios fines. Si no explica las capacidades potenciales de la API, entonces los nuevos usuarios no sabrán cómo usarla y experimentarán una lenta adopción de productos. Los usuarios Potential de una API usan la documentación como una manera de tomar la decisión de usar o no su producto.

El Ir a la Fuente de los Miembros del Equipo para referirse a los Objetivos de la API

Los miembros del equipo interno de su organización pueden referirse a la documentación de la API cuando quieren familiarizarse con los objetivos de su API. Incluso aquellos que no participaron directamente en la construcción de la API o en la escritura de la documentación comprenderán el propósito de la API y podrán apoyar el trabajo del equipo de desarrollo de la API.

Permite identificar errores rápidamente y problemas

Cuando documentas la API, esto te permite identificar rápidamente errores y problemas como resultado de la prueba de la API para documentar todas sus características. Si tu API no funciona como está diseñado, esta retroalimentación puede ser transmitida al equipo de desarrollo de la API, quien puede tomar medidas para solucionar cualquier problema. El resultado es una API más profesional y eficaz que funciona como se esperaba.

La estructura de la documentación de API – Diseño y función

Una línea externa

El contorno de la documentación de su API también es conocido como la descripción. Contiene un resumen de la API y su propósito, y puede informar a los usuarios potenciales sobre los beneficios de usar esta API sobre otros.

Tutoriales

Los tutoriales forman la parte principal de la API y su propósito es enseñar a los usuarios el concepto de la API y cómo utilizarla eficazmente. Normalmente contiene guías paso a paso para cómo integrar la API y cómo se ve el funcionamiento apropiado.

Autenticación

La autenticación es la forma en que el proveedor mantiene los datos de la API a salvo para los desarrolladores y usuarios finales, por lo que podría tener múltiples esquemas de autenticación. La documentación de la API explica cada método de autenticación para que los usuarios entiendan cómo acceder a la API.

Definición de punto final

Las definiciones de los endpoints de la API son el punto en el que la API se conecta con el programa de software. El punto en el que la API interactúa con otro sistema se considera el punto final, y puede incluir una URL del servidor o servicio.

Estado y códigos de error

Las APIs utilizan los códigos de estado y de error para informar a los desarrolladores cuando la API no está funcionando como se esperaba, junto con una descripción del estado o error. Pueden contener instrucciones sobre cómo proceder y resolver los errores que se les presenten.

Ejemplos

Cuando los usuarios entienden cómo funciona la API, es bueno darles ejemplos que muestran ejemplos exitosos de llamadas, respuestas, manejo de errores y otras operaciones que pueden encontrar al usar la API.

Glossary

En lugar de explicar cada término técnico a lo largo de su documentación, puede enlazar a un glosario que proporciona definiciones de términos, esquemas y más.

Cómo escribir tu primera documentación API

Reconocer al público

Antes de empezar a crear cualquier tipo de documentación de la API, debe asegurarse de entender la audiencia prevista para su producto. Debes saber exactamente en qué tipos de usuarios quieres centrarte los beneficios particulares que obtendrán de la API, y la forma en que usarán su documentación en el campo.

Es importante recordar que su público potencial para la documentación de su API normalmente puede dividirse en dos grupos. El primero son los desarrolladores que interactuarán con la API y la utilizarán activamente que requerirá más documentación a lo largo de las líneas de tutoriales y ejemplos de código. El segundo público se compone de líderes técnicos y gestores de productos que evaluarán la API y cómo se ajusta a los objetivos empresariales.

Crear un Mapa del recorrido del Usuario

Cuando los usuarios están interactuando con su documentación API, pueden estar en una de muchas etapas del recorrido del usuario. Los usuarios que estén evaluando primero su API necesitarán documentación para decirles exactamente lo que su API puede hacer y los problemas que resuelve, así como definiciones de funciones y puntos finales, y cómo su API es diferente de otros proveedores ahí.

Crear un mapa del recorrido del usuario le permite atender a los usuarios que se encuentran en diferentes etapas y proporcionar una mejor experiencia de desarrollador. Los desarrolladores serán soportados cada paso del camino en lugar de preguntarse qué puede hacer tu API por ellos.

Comenzar con Directrices para Escenarios Comunes

Hay algunas de las funciones más comunes para las que se utilizará tu API para que puedas crear pautas para estos escenarios. Debes asegurarte de abordar los casos típicos de uso de tu API para que los nuevos desarrolladores puedan entender cómo utilizar correctamente la API. Cada caso de uso debe tener una sección separada e incluir un mensaje de ejemplo en cada uno de ellos.

Proporcionar directrices para escenarios comunes ayudará a tus desarrolladores a ponerse en marcha sin tener que luchar demasiado por sí solos. También muestra a los desarrolladores de lo que tu API es capaz y puede persuadirlos de que elijan tu API sobre otros.

Añadir muestras de código

Añadir muestras de código a la documentación de tu API ayuda a los desarrolladores a empezar a probar rápidamente tu API y a entender todo su potencial. Cada endpoint debe venir con sus propias muestras de código para que los desarrolladores puedan adaptar el código para cumplir con su especificación exacta y probar las funciones más importantes de los extremos.
Las muestras de código muestran a los potenciales desarrolladores cómo funciona tu API y les hace más fácil empezar porque simplemente pueden copiar y pegar el código. Puedes incluir muestras de código en todos los diferentes lenguajes de programación en los que tu API está disponible.

Mensajes de Error de Llamada y códigos de estado

Los mensajes de error y los códigos de estado deben incluirse en tu documentación porque dicen a tus desarrolladores cuando han realizado o no una llamada API exitosa. Cada mensaje o código debe incluir una breve descripción de por qué se muestra para que los usuarios puedan entender lo que sucede cuando interactúan con el sistema.

Las descripciones que acompañan a los mensajes de error deben construirse con el propósito de mostrar a los usuarios cómo resolver los problemas por sí mismos. Deberían ser detallados y específicos para que los usuarios puedan entender por qué el sistema está devolviendo un error.

Mantiene tu documentación

Después de publicar su documentación por primera vez, debe asegurarse de revisarla regularmente para mantener el contenido actualizado. No hay nada más desalentador para los posibles usuarios de tu API que una documentación incompleta o inexacta.
Si no mantienes la documentación actualizada y efectiva a lo largo del tiempo, los desarrolladores no podrán utilizar tu API y experimentarás una disminución en su adopción. Cada vez que haces una actualización o publicas una nueva característica, esto debería reflejarse en la documentación y ser considerado una parte esencial del envío de su API.

Mejores prácticas de documentación API

1. 1. Adoptar el idioma claro

Al escribir la documentación de la API, no conocerás el nivel de experiencia de los usuarios que la consultarán. Por eso, es importante utilizar un lenguaje claro y comprensible para que todos puedan entenderlo.

2. Incluye documentación de referencia

La documentación de referencia para APIs es una lista completa de objetos y métodos expuestos por la API, junto con una descripción de cómo utilizar cada uno. Esto enseña a los desarrolladores todo lo que está disponible y cómo funciona.

3. Ejemplos de implementación

Con la mayor frecuencia posible debe utilizar ejemplos para el funcionamiento de su API, que se pueden encontrar dentro de cualquier área de referencia de su documentación. Puede ser cualquier cosa que ilustre el concepto de la API y ayude a los desarrolladores a comenzar con sus propias llamadas API.

4. Pon a alguien a cargo de los documentos

Necesitas a alguien en tu equipo cuyo trabajo es supervisar la experiencia del desarrollador de la documentación de tu API. Podría ser todo su trabajo si son un escritor técnico o una responsabilidad a tiempo parcial si también son un desarrollador.

5. Cubre diferentes tipos y temas

Debe asegurarse de que la documentación de su API es completa y que cubre referencias, guías y ejemplos. Si algunas áreas faltan, entonces usarás esta información para decidir dónde enfocar esfuerzos futuros.

6. Incorporar documentación en procesos

Su documentación y su API deben desarrollarse en tandem. Con la evolución de la API, viene el desarrollo de su documentación, especialmente junto con las nuevas versiones de funciones. Automatiza todo lo que puedas y ahorra tiempo con tu documentación.

7. Proporcionar guías de inicio rápido

Las guías de inicio rápido (Quickstart) son la mejor manera de integrar nuevos desarrolladores con tu API y ayudarlos a comenzar a utilizarla. Estas guías contienen instrucciones sobre cómo usar tu API, así como ejemplos de código que facilitan el acceso a ella

Además, revisa nuestro blog en Lista de verificación de documentación

Mejores ejemplos de documentación de API

He aquí algunos ejemplos de documentación real de la API que puede utilizar para inspirar sus propios esfuerzos.

GitHub API

La API de GitHub es una API REST que los desarrolladores pueden usar para conectarse con la plataforma de GitHub, que es una herramienta de desarrollo colaborativo para proyectos de software. GitHub ofrece documentación completa de inicio rápido para ayudar a los desarrolladores a entender la API y las secciones detalladas para cada aspecto del uso de la API.

Documentos API Twilio

La API de Twilio es otra API REST que los desarrolladores pueden usar para conectarse con la plataforma Twilio, una plataforma de participación de clientes que permite a las empresas comunicarse a escala. La documentación contiene todo lo que necesita para integrarse con Twilio, incluyendo autenticación con HTTP y SDKs.

Dropbox API docs

La API de Dropbox permite a los desarrolladores crear integraciones con la plataforma de intercambio de documentos de Dropbox. Ofrece componentes precompilados que ayudan a los usuarios a incrustar componentes de Dropbox, junto con una referencia API para permitir a los desarrolladores construir aplicaciones e integraciones personalizadas. También ofrece varios SDKs oficiales para lenguajes de programación populares.