Las APIs están en todas partes, pero... ¿y su documentación?

En un mundo conectado, las APIs son el pegamento que une todas las piezas que forman nuestra vida diaria. Y de la misma forma que un pegamento solo es potente si sabemos en qué material utilizarlo y conocemos sus propiedades, las APIs son tan útiles como su documentación permita.

BBVAOpen4U
|
04 Ene. 2018

Sin embargo, la documentación de las APIs va más allá de ser capaz de dar utilidad. Permite explicar los motivos detrás de su desarrollo; sirve de canal de comunicación primario entre desarrolladores en ambas partes del servicio; ayuda a descubrir nuevas capacidades, y, por último, es la responsable directo de la popularidad e implantación de una API.

Dicho de otra forma, una API similar o ligeramente inferior o capaz con una gran documentación será más exitosa que otra cuya documentación sea escasa, mal organizada o difícil de comprender. A pesar de que los desarrolladores suelen estar acostumbrados a tratar con múltiples problemas lógicos en su día a día, pocas cosas son tan agradables para un programador como implementar métodos intuitivos de una API o un servicio que les ayude en su trabajo.

Una gran documentación no solo ayuda a hacer entender los diversos métodos y posibilidades de una API, también dirige la mente de los desarrolladores hacia nuevas oportunidades que desconocían y que mejore sus aplicaciones. Más desarrolladores trabajando sobre una API tradicionalmente se traduce en más recursos disponibles, debido a una mayor capacidad de ingresos asociados con la misma, o incluso la posibilidad de expandir el equipo de desarrollo.
 

Qué elementos no pueden faltar

Con la Payments API de BBVA como ejemplo, vamos a enumerar los factores que no pueden faltar a la hora de presentar una excelente documentación para que los desarrolladores puedan trabajar de forma cómoda, entender nuestros planteamientos y extender las funciones de su software con nuevas características.
 

1. Un índice con sentido

Con enlaces a las referencias de cada método y explicando un historial de los cambios, para que desarrolladores veteranos puedan ver qué ha cambiado de un solo vistazo.

 

2. Descripción de cada método

De forma detallada y explicando todos sus argumentos, con ejemplos concretos para cada uno.

3. Respuestas de cada método

No solo hay que mostrar qué introducir, también qué esperar. Una descripción concreta de los retornos del método, tanto correctos como posibles errores, con sus correspondientes soluciones.


4. Sandbox

Permite a los desarrolladores hacerse una idea rápida de cada método de una forma segura y sin tener que configurar nada, ni solicitar claves de acceso, ni registrarse o formalizar ningún compromiso.

 

Cómo escribir bien una documentación
 

  1. El primer paso es planificar la documentación mientras planeas la API. De hecho, debería ser escrita paso a paso al mismo tiempo que la propia API para ir manteniendo una referencia interna durante su desarrollo. De esta forma luego será más fácil convertirla en una documentación para terceros.
     
  2. Debería tener contar con una página de inicio donde se describa la API de forma general, así como enlaces a las posibilidades y capacidades de la misma para empezar a ahondar en ella. Contar con un buscador y mantener unas URL claras para poder ser rápidamente consultadas a posteriori, es también indispensable.
     
  3. Cada método debería estar explicado de forma concisa pero clara. Un punto clave aquí es mantener una política de nombres descriptivos de los recursos y métodos. Tras la descripción inicial se deberían especificar los argumentos de entrada del método y los retornos esperados del mismo.
     
  4. En cuanto a los argumentos, deben tener especificado el formato y limitaciones permitidos en todo momento, cuáles son necesarios y cuáles son opcionales. Sus nombres también tienen que facilitar su rápida digestión por otros desarrolladores, y su orden tener sentido lógico. Agrupar los argumentos por su relación directa y por la obligación de estar presentes es una forma fácil y común de hacerlo.
     
  5. Las salidas o retornos son quizá más complicados. No solo hay que explicar cuáles son los esperados en caso de que salga bien, también debe detallar qué tipo de errores pueden darse. Los errores deberán ser especificados y sus posibles soluciones detalladas.
     
  6. Por último, se han de ofrecer múltiples ejemplos de uso de cada método que tengan suficiente variedad como para representar los casos de uso más comunes del mismo. Si se puede mantener en varios de los lenguajes de programación más habituales, mucho mejor. En caso contrario, hacer disponible un caso único con el lenguaje de programación más común o el único disponible para utilizar la API, o incluso con pseudocódigo que siga lógicas comunes a otros lenguajes reales.

 

Si quieres conocer más sobre las APIs financieras de BBVA, visita esta web.

¡Suscríbete!

Recibe nuestro boletín semanal. No te pierdas nuestros trucos, consejos, artículos y los eventos más innovadores.