En muchas ocasiones los desarrolladores tienden a pasar por alto que crear, organizar y mantener un set de APIs también necesita de una labor muy intensiva de gestión de la experiencia de usuario. Al fin y al cabo, serán otros desarrolladores los que tendrán que utilizarla.
Una API es solo tan potente como las aplicaciones y programas que conecta, y si los desarrolladores encuentran difícil incorporar una API puede afectar al comportamiento final de la misma. Un consejo siempre certero para los desarrolladores es crear APIs que ellos mismos querrían usar.
El camino a recorrer para crear una API con una buena experiencia de usuario, o experiencia de desarrollo, no es para nada complicado y se basa en un listado de reglas en cierto sentido abstractas, pero que hay que tener en cuenta en todo momento para que el producto final mantenga una cohesión y sea fácilmente entendible por un desarrollador externo.
Entendibles e intuitivas
Dicho de otra forma: una API cuya documentación sea una lectura secundaria. Cuyos métodos propios digan a gritos lo que hacen, cómo se solicitan y qué datos devuelven. Obviamente todas las documentaciones tienen que ser leídas, pero con una vez debería ser suficiente.
No solo se trata de crear un sistema de “naming” constante y que siga estándares de la industria. El contenido a retornar también debe ser anticipado por el desarrollador de forma intuitiva.
Cómo no hacerlo: diseña métodos con nombres genéricos y variables numéricas basadas en identificadores externos que no son reconocibles a primar vista:
/api/cargar_datos?valor_predeterminado=3
Recomendación: utiliza métodos descriptivos en los nombres de los métodos y los argumentos.
/api/lista_de_usuarios?cantidad=10&ordenar=nombre
Extendible
Una API no existe, por definición, sola e independiente del resto de aplicaciones en un refugio digital. Son ampliadas, verriondas y refactorizadas a lo largo del tiempo gracias al feedback de otros desarrolladores o a las necesidades del propio proyecto. La extensibilidad es clave en dos aspectos:
• Extensibilidad propia: que la API sea capaz de crecer con nuevos métodos en el futuro de forma que se mantengan los principios anteriormente mencionados de intuición y claridad.
• Extensibilidad de terceros: que la API que estés diseñando ayude a otros desarrolladores a crear mejores aplicaciones, que vaya más allá de ofrecer una conexión entre dos puntos.
En la experiencia de usuario, gran parte del segundo punto se realiza con “callbacks”, llamadas de retorno que definen la ejecución de los datos devueltos por la API que hemos diseñado.
Organizar que los datos que incluimos en la respuesta sean suficientes puede ayudar a diseñar interfaces de usuario más ágiles, con menos código y que además hagan más fácil el desarrollo.
Cómo no hacerlo: devuelve pocos campos, con valores no reconocibles o que necesiten de llamadas extra en la mayoría de ocasiones.
{ “usuarios”: [ 2, 3, 4, 5 ] }
Recomendación: los datos que devuelve tu API deben ser descriptivos y con capacidad para extender el software que se conecta
{ “usuarios”: [{
“id”: 2, “nombre”:”Laura”, “fecha_registro”: “2008/09/29”},
“id”: 3, “nombre”:”Sara”, “fecha_registro”: “2008/09/29”},
“id”: 4, “nombre”:”Ramón”, “fecha_registro”: “2008/09/30”}
]}
Estándar
No reinventes la rueda. En casi cualquier campo del software muchos otros desarrolladores con más experiencia y más tiempo disponible han creado algún tipo de “buenas prácticas” para la experiencia de usuario a la que se debe acoplar la API que estás desarrollando. Descúbrelas, apréndelas y aplícalas.
Busca comentarios de otros diseñadores y desarrolladores durante la etapa de planificación inicial de tu API. Saber cuáles son las necesidades finales de la interfaz y la experiencia a conseguir es clave.
Si la API va formar parte de un intrincado ecosistema de conexiones, sobre todo en entornos corporativos, vuelve a primar los dos consejos iniciales: hazla intuitiva y extendible.
Si la UX de tu API es mala, puede llevar al traste el trabajo de toda la organización que hay detrás, acabando con posibles acuerdos futuros, porque una API competidora se adapta mejor a sus funciones, lo hace con menos desarrollo por parte de terceras partes, o está diseñada con estándares de la industria reconocidos.
¿Te interesan las APIs financieras? Descubre todas las que te ofrece BBVA