Es fundamental mantener y distribuir una buena documentación de tu API, aún más si aplicas un modelo de API Economy. Los desarrolladores que deban crear aplicaciones basadas en tu API agradecerán que toda la información, contenidos y ejemplos, se encuentren ordenados y que utilices un lenguaje extrapolable a cualquier persona que no esté familiarizada con el entorno o con tu modelo de negocio.
Artículos recomendados antes de seguir la lectura:
- ¿Cómo mantener mi API RESTful?
- ¿Cómo escalar mi API REST?
- API Economy, ¿Tu nuevo modelo de negocio?
- ¿Como debo mejorar la seguridad de mí API?
¿Por qué es importante documentar una API?
Una documentación bien estructurada facilita el proceso de aprendizaje sobre el nuevo entorno que se desarrollará basándose en tu servicio API. Al igual que lo hacen las ‘instrucciones que cumplan con su propósito’, deben cumplir ciertos requisitos que diferencian una buena documentación “simplificada” de una mala documentación con páginas indescifrables en idiomas que ni conocías su existencia.
Es una de las piezas básicas que determinan la experiencia de un desarrollador al hacer uso de tus servicios API, y va más allá del formato de respuesta API o el método de autentificación. La documentación debe ser interactiva, mostrando a los desarrolladores la estructura y la organización que les facilitará el trabajo, de modo que no tengan que pasar tiempo investigando las funciones o perderlo en pruebas totalmente improductivas.
Herramientas de documentación API
Desarrollar una API es duro por el esfuerzo dedicado al diseño y la implementación o el tiempo que debe dedicarse a la documentación y a su mantenimiento para que los desarrolladores que vayan a usarla tengan claro su funcionamiento. Es por ello que una herramienta de documentación API te facilitará el trabajo.
Existen diversas herramientas, aunque algunas de las más conocidas sean RAML (lenguaje de modelado API RESTful), Slate y Swagger; éste último es uno de los estándares más utilizados y fue elegido por Open API Initiative como modelo de especificación API.
¿Qué es Swagger?
Swagger es una herramienta extremadamente útil para describir, producir, consumir y visualizar APIs RESTful. El principal objetivo de este framework es unificar el sistema de documentación API con el propio código desarrollado para que esté sincronizado en cada cambio. Con Swagger documentas tu API al mismo tiempo que creas una nueva implementación.
Swagger es multiplataforma, con soluciones para Scala, Java, Javascript, Ruby, PHP o ActionScript para generar toda la documentación y su sandbox correspondiente. Además, existen distintos módulos para acoplar a tus proyectos Node.js, Grails, Scala Play, Spring MVC, Symfony o Ruby, entre muchos otros.
Como resultado final proporciona una interfaz web gráfica a modo de sandbox donde puedes testear los endpoints API a la vez que estás consultando la documentación. Es útil tanto para desarrolladores como para usuarios no experimentados permitiendo probar en la misma documentación antes de programar:
Swagger cuenta con las anotaciones que deberán incluirse en cada endpoint de la API, de forma que después se autogenere la documentación API de la manera más completa posible. Analicemos la documentación de la API “Pet Sotore” del ejemplo, a la izquierda las annotations y a la derecha el resultado:
Las capturas que acabas de ver, son annotations en formato YML, también disponible en JSON, creando un único fichero con toda la documentación de tu API. Aunque a mí me gusta más añadir las annotations a la vez que programo, sincronizado cada cambio en el codigo con las annotations de la documentación. Veamos un ejemplo PHP con annotations en el controlador:
Te facilito la documentación de Swagger con todas las annotations disponibles para que puedas encontrar las diferentes opciones y adaptarlas a tu API.
Si buscas la forma de documentar tu API de forma ágil, ¡Swagger es lo que andas buscando!
Buenas prácticas para mantener una buena documentación API
Descripción endpoint detallada
Amplía la descripción de los endpoints con texto explicativo de la forma más detallada posible, utilizando siempre un lenguaje comprensible, intentando no adquirir un tinte demasiado especializado o técnico porque no todos los desarrolladores tienen la misma experiencia o están familiarizados en el entorno de tu API.
Aunque las API actúan como una capa de abstracción que sirve para ocultar ciertos detalles de las operaciones que se ejecutan, lo mejor para no confundir a los desarrolladores es precisamente evitar abstracciones en la documentación.
Detalla los parámetros y las respuestas esperadas
Lista todos los parámetros de entrada y salida que proporcione cada endpoint, además de los tipos de respuesta HTTP esperados; ésto evitará sorpresas a los desarrolladores que consuman tu API teniendo en cuenta las diferentes casuísticas que deberán valorar en el momento de desarrollar un frontend apropiado.
Un entorno multiplataforma
Debes señalar los diversos lenguajes de programación aceptados por tu API e, incluso, dar los ejemplos en cada uno de ellos. Una posibilidad es permitir que los usuarios elijan el lenguaje de programación que prefieran desde el principio, como es el caso de la documentación de Stripe API que ofrece una opción entre Curl, Ruby, Python, PHP, Java, Node.js, Go o .NET
Versionado
El versionado es la clave del éxito a largo plazo de tu API. Al igual que cuando giras la llave de tu puerta para entrar o salir de casa siempre esperas que sea la misma llave o puerta, si tu pareja cambia la forma de esa llave o ha pintado la puerta de otro color necesitas un aviso previo de dichos cambios para no perderte. Lo mismo les sucede a los desarrolladores que esperan que el funcionamiento no se vea alterado por nuevas implementaciones o innovaciones.
Es muy importante facilitar el acceso a la documentación API de todas las versiones que se encuentran en producción, pero también lo es el dar acceso a la documentación API de versiones o funcionalidad deprecated que ya no lo estén.
¿Te has encontrado con un ‘404 Not Found’ en alguna documentación?
Nosotros sí… y es de muy mal gusto. Las funcionalidades deprecated deben ser informadas y hacer referencia a los nuevos métodos que sustituyen dicha funcionalidad o endpoint. Se debe ofrecer una salida al desarrollador que utiliza o utilizó una función que ahora no se encuentra disponible, ofreciéndole una nueva solución.
Tutoriales como ejemplo
Sería fantástico si pudieras añadir tutoriales que actúan como un manual para mostrar a los desarrolladores ciertas funciones y ejemplos específicos de lo que pueden hacer con tu API. Un ejemplo es este tutorial de Stripe para construir un formulario de pago personalizado. Conviene añadir en cada demostración el código que se requiere para llamar a la API desde la aplicación y ofrecer ejemplos del tipo de respuesta que se obtendrán.
Conclusión
Crea una buena documentación, tutoriales y sobre todo un canal de soporte para brindar a los desarrolladores toda la ayuda que puedan necesitar. Documentar correctamente tu API permite a tus desarrolladores, internos o externos, a mantener una única fuente de información, evitando errores de versionado. Es aún más relevante disponer de una buena documentación si aplicas un modelo API Economy en tú organización, tus clientes deben disponer de todas las facilidades para desarrollar servicios ágilmente mediante tu servicio API.
¿Documentas tu API? ¿Tu API genera empatía con el desarrollador? Si tienes dudas sobre cómo documentar tu servicio API, escríbenos y te ayudamos a desarrollar tus proyectos.
