BBVA API Market
Una de las piezas fundamentales que determinan la experiencia de usuario de un desarrollador cuando va a aprovechar los servicios que ofrece una API (interfaz de programación de aplicaciones) va más allá del formato de la web o del proceso de autenticación: es la documentación que la acompaña.
Se trata de un libro de instrucciones interactivo que muestra a quien accede a la plataforma su estructura y organización para facilitarle el trabajo, evitando que tengan que entretenerse en investigar las funcionalidades o perderse en pruebas improductivas. Y como cualquier manual que se precie, debe cumplir ciertos criterios que diferencian un buen esquema de un simple compendio de páginas indescifrables.
La documentación de una API no debería constituir únicamente una lista de los diferentes dispositivos en los que puede mostrarse el contenido –smartphones, tabletas, televisores inteligentes, consolas, etc.− y sus correspondientes especificaciones técnicas y procedimientos. Lo ideal es que refleje todo un ecosistema de contenido que explique al usuario como interactuar con la interfaz.
Un buen ejemplo de todo esto es la documentación de la API de Stripe, uno de los servicios de pago online más extendidos y una alternativa que cada día roba más adeptos a PayPal, que decidió mejorar la imagen de su propia API (y la documentación de la misma) debido a la competencia.
El primer paso consiste en elegir la herramienta con la que generar la documentación, en el caso de que no dispongamos de un software propio. Existen diferentes opciones en este sentido, aunque algunas de las más conocidas son RAML (de RESTful API modeling language), Slate y Swagger. Este último constituye uno de los estándares más utilizados (también por PayPal) y elegido por la Open API Initiative como modelo. En el caso de Stripe, han adaptado el formato y estilo de la documentación de la API de CoffeeScript, pero han creado su propio software para producir la documentación.
Sea cual sea la elección, la organización del índice interactivo debe basarse en las distintas tareas y diferenciar los temas por categorías para presentar la información de forma clara y legible. No obstante, tampoco hay que exagerar el número de pestañas ni de páginas, sino optimizar el espacio y colocar cerca los temas relacionados.
Tras este apunte inicial, deben incluirse una serie de contenidos imprescindibles. Uno de ellos consiste en una lista con todas las funcionalidades que los desarrolladores pueden obtener de la API. Esto incluye todos los tipos de datos que ofrece para las aplicaciones de terceros y las especificaciones que requiere cada función.
Otra parte importante son las guías, que sirven de complemento de lo anterior. Amplía el registro de funcionalidades con texto para explicar cada apartado más detalladamente, utilizando siempre un lenguaje comprensible, sin adquirir un tono demasiado especializado o técnico, porque no todos los desarrolladores tienen la misma experiencia.
Además, pueden añadirse tutoriales que actúan como un manual para mostrar a los desarrolladores ciertas funciones y ejemplos específicos de lo que pueden hacer con la 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 requeriría para llamar a la interfaz desde la aplicación y ejemplos del tipo de respuesta que se obtendría.
Asimismo, no hay que olvidar señalar los distintos lenguajes de programación que admite la interfaz e incluso poner los ejemplos en cada uno de ellos. Una posibilidad es permitir a los usuarios elegir el idioma que prefieren desde el principio, como hace la documentación de la API de Stripe, que da a elegir entre Curl, Ruby, Python, PHP, Java, Node y Go.
Otro recurso que puede resultar útil a los desarrolladores es una lista complementaria de los distintos formatos y dispositivos que pueden hacer peticiones a la API, y ejemplos de los tipos de funciones que pueden utilizar. Les permite acceder a la información por una vía alternativa, en lugar de buscar por tema. También existe la posibilidad de añadir una especie de “botón de inicio rápido” para que los usuarios de la API puedan probar alguna funcionalidad básica con un solo clic. Así lo hace Stripe:
Aunque las APIs actúan como una capa de abstracción –sirve para ocultar ciertos detalles de las operaciones que se ejecutan−, lo mejor para no confundir a los desarrolladores es precisamente evitar las abstracciones en la documentación. En otras palabras: sembrar ese libro de instrucciones de ejemplos que muestren las interacciones y el resultado de cada una de ellas, con lenguaje entendible y el código asociado.
Generar una documentación con el contenido y el formato adecuados facilitará el proceso de familiarización de los desarrolladores que trabajan con la API y su experiencia de usuario. Una manera de incentivarles a seguir utilizándola.
Taking a customer through the entire buying process until it is formalized is an arduous journey and one that faces the constant possibility of the customer leaving. However, there are ways to make the buying decision happen if you are given facilities such as agile, secure financing.
In a connected world, APIs are the glue that keeps all the parts that form our day-to-day lives in place. The same way the power of glue depends on the material it is used on and the knowledge of its properties, APIs are only as useful as their documentation allows for.
There are different solutions to monitor the performance of an API, in terms of traffic, quality and speed of the answers it provides. Detecting faults in the code or quantifying the generated revenues are also some of the options offered by these useful tools.
