Para responder a esta pregunta hay que tirar de lógica: todo desarrollador debería documentar bien su API porque esa documentación es, en realidad, el “libro de instrucciones” que el resto de personas usarán para integrarse con ella. Cuanto más sencillo, directo y claro sea lo que explicamos en él, más rápida será esa integración y mejor funcionará todo.
La era de la conectividad
La conectividad es el pilar básico sobre el que el que se ha ido desarrollando Internet tal y como la conocemos hoy en día. Un espacio en el que usuarios de todo tipo pueden conectarse entre sí y beneficiarse el uno del otro, ya sea compartiendo una simple conversación o realizando la transacción económica más compleja del mundo.
En este escenario, las APIs (Interfaz de Programación de Aplicaciones) son precisamente las bisagras, los hilos de conexión que facilitan que usuarios diferentes se conecten sin problemas entre sí y puedan sacar un beneficio mutuo.
Pero para que esta conexión se produzca de la forma más sencilla, rápida y eficaz posible, toda API que se precie deberá tener una buena documentación: interactiva, que muestre bien la estructura y evite que los desarrolladores tengan que perder tiempo investigando o haciendo pruebas que no sirven para nada.
En este sentido, Dani Calle, Team Leader de Core, lo tiene claro: documentar bien una API “refuerza la gestión del conocimiento” pero es importante hacerlo pensando en calidad y no en cantidad. “Como decía mi uno de mis primeros jefes: Si no está documentado… es que no has trabajado.”
Claridad, concisión y precisión
Guardarse secretos en este campo no tiene mucho sentido si uno quiere que la API sea utilizada por el mayor número de personas posible y de la manera correcta. De ahí que sea tan importante dedicarle tiempo a pensar cómo se puede estructurar bien todo el contenido de esa documentación.
Lo que queremos es que se nos entienda. Así que hay que dejar los lenguajes crípticos y los misterios para la intimidad. La información que ofrezcamos de nuestra API, bien ordenada y explicada, es clave para que otros desarrolladores que tengan que diseñar aplicaciones basadas en ella puedan hacerlo de forma fácil.
“Si quieres que usen lo que ofreces, debes comunicarlo. Un mecanismo para ello es tener una documentación atractiva y usable, que refleje el estado del arte de tus apis y, sobretodo, que estas apis están vivas…”, remarca Dani Calle.
Empezar con buen pie
Antes de nada, debemos definir el índice, es decir, plantearnos cómo vamos a organizar la información, punto por punto, tema por tema. Este índice siempre deberá ser interactivo y no demasiado extenso en número de páginas y pestañas para evitar que el usuario se pierda.
También conviene dejar bien claros los lenguajes de programación que admite la interfaz y citar todos aquellos dispositivos y formatos que pueden lanzar peticiones a nuestra API.
Funcionalidades de la API
Uno de los puntos clave e imprescindibles en la documentación de nuestra API es dejar bien claro desde el principio qué ofrece la misma. Detallar las funcionalidades y las especificaciones de cada una, así como todo lo que brinda a las aplicaciones de terceros, ayudará al resto de desarrolladores a entender en qué consiste nuestra API de un primer vistazo y qué oportunidades le ofrece.
Incluye siempre unas guías con las que desgranes toda la información de forma que puedan entenderlas tanto los desarrolladores con mucha experiencia como los que no tienen tanta. De este modo, ampliarás el tipo de público al que puede interesarle trabajar con tu API.
Habla con ejemplos
Utilizar ejemplos en la documentación de nuestra API -tanto para explicar cada una de sus funcionalidades y las posibles respuestas como para mostrar con más detalle algunas funciones más complejas- permitirá al usuario sacarle más partido sin tener que invertir demasiado esfuerzo.
Una fórmula dinámica y sencilla para introducir ejemplos en la documentación de nuestra API es incluir algún que otro tutorial en el que desarrollemos con detalle las funciones más destacadas así como los procesos más complejos.
Y, por último, como el tiempo es oro, no te olvides de añadir atajos que ayuden a otros desarrolladores a hacer pruebas rápidas con la API, en especial para todo aquello que sea de especial relevancia y que facilite el aprendizaje del nuevo entorno.