El libro de instrucciones de la API: por qué una buena documentación es esencial

El libro de instrucciones de la API: por qué una buena documentación es esencial
El libro de instrucciones de la API: por qué una buena documentación es esencial

BBVA API Market

Tanto los principiantes como los ya experimentados usuarios de cualquier tipo de software necesitan alguna vez consultar la guía de instrucciones que explica su funcionamiento y características técnicas. Sin embargo, al igual que ocurre con otro tipo de productos, hay ocasiones en las que, por mucho que se lean y relean, estos documentos resultan incomprensibles incluso para los profesionales.

Aunque las APIs (interfaces de programación de aplicaciones) no constituyen un software en sí mismas, deben ir acompañadas de una documentación incluso más detallada y exhaustiva para que los desarrolladores tengan clara su estructura y puedan utilizarlas de forma rápida y eficiente. 

Además de facilitarles el trabajo, una API bien documentada mejora su experiencia, acelera el proceso de integración entre sistemas y fomenta que quienes ya la utilizan se la aconsejen a sus compañeros, mejorando la reputación de la empresa y el servicio.  

El proceso, por tanto, no puede reducirse a integrar una serie de páginas en HTML en las que se describa cómo realizar la autenticación, los tipos de entornos posibles y las utilidades de cada recurso. Es necesario proveer a los desarrolladores de una experiencia visual e interactiva, que les permita probar las distintas funcionalidades directamente, para lo que existen distintas opciones que los responsables de la API deben valorar para elegir la que mejor se adapte a sus necesidades.

Una de ellas es API Blueprint, que se basa en Markdown, un lenguaje sencillo para marcar documentos que consta de una sintaxis en texto plano que la herramienta convierte a HTML y otros formatos. De esta manera, resulta fácilmente comprensible para humanos y, aunque su propietaria es la empresa Apiary, la mayoría de sus funcionalidades son open source

Además, la lista de posibilidades incluye especificaciones como RAML (de RESTful API Modeling Language), IO Docs y Slate. Esta última herramienta, también de código abierto y basada en Markdown, proporciona un resultado elegante, bien estructurado y de uso intuitivo. Permite concentrar toda la documentación en una sola página, poniendo a la izquierda la descripción de la API y a la derecha ejemplos de código para cada funcionalidad.

Sin embargo, quizá la más popular sea Swagger, un lenguaje diseñado para que la documentación evolucione al mismo tiempo que la implementación, ya que puede ser generada automáticamente por medio de anotaciones en el código. Estructura la guía de uso en una interfaz visual donde los desarrolladores pueden no solo consultar la información, sino también probar los comandos de interacción y observar los resultados en directo.

En busca de un lenguaje universal

Swagger, fundado en 2010 y donado a la comunidad por la firma SmartBear, constituye actualmente uno de los estándares más utilizados, que acepta la mayoría de lenguajes de programación y está mantenido por una amplia comunidad de profesionales.

Prueba de su éxito es que la especificación ha sido la elegida por la recientemente lanzada Open API Initiative. Se trata de un proyecto colaborativo de la Fundación Linux respaldado, entre otros, por Google, Microsoft, PayPal e IBM para estandarizar la descripción de las interfaces de programación, proporcionando un patrón válido en cualquier parte del mundo, empresa y entendible por todos los desarrolladores. 

No obstante, continúan surgiendo otras posibilidades que mejoran algunos de los resultados de Swagger. Tanto su interfaz de usuario, como la solución interactiva de código abierto de LucyBot, basada en Swagger 2.0, proporcionan pantallas con un esquema claro e intuitivo, facilitando la tarea a los desarrolladores menos experimentados que solo buscan aprovechar cierta funcionalidad de una API.

Sea cual sea el método elegido, la documentación de la API debe estar enfocada a quienes van a utilizarla, es decir, tanto a los desarrolladores externos como a los propios proveedores del servicio que la mantienen y mejoran. Atender a sus necesidades y estudiar el feedback de estos usuarios permitirá además identificar aquellos aspectos que entrañan más dificultad para clarificarlos. 

Si quieres conocer las APIs financieras de BBVA, puedes visitar este site

También podría interesarte