Header Ads Widget

Ticker

6/recent/ticker-posts

Cómo diseñar API sin fricción


 Cuando se trata de fabricar productos, los diseñadores exitosos se dan cuenta de que el usuario final debe ser el objetivo final. El usuario realmente debe ser considerado en cada decisión que se tome. De hecho, es tan importante que el estudio de la experiencia del usuario (UX) es una disciplina dedicada.

Por supuesto, la importancia del usuario no se aplica solo al diseño del producto; este principio es de aplicación universal. Esto incluye aplicaciones más abstractas, como el diseño de API . Al considerar al usuario desarrollador durante todo el proceso de diseño, el resultado final es algo que no tiene fricciones: fácil de aprender y fácil de seguir.

Entonces, ¿qué significa llevar usabilidad a la tabla de diseño de API? Dependiendo del cronograma, el presupuesto y el estado actual de la API, se aplicarán diferentes técnicas y mejores prácticas. Comience con algunos que parezcan más útiles, agregando más a medida que el equipo pueda. A continuación se describen diez técnicas y métodos que pueden utilizarse para convertir a los visitantes del portal de desarrolladores en consumidores de API y retenerlos como usuarios activos.

1. Proporcione una sólida introducción

La experiencia del consumidor de API comienza antes de que se escriba cualquier código, durante la investigación y la planificación. Esto significa que la experiencia realmente comienza con el sitio y la documentación. Una experiencia útil e informativa puede ayudar a que una API se destaque y hacer que los usuarios desarrolladores vuelvan por más.

Entonces, ¿qué constituye una buena experiencia inicial? Algunos componentes son clave. Una introducción es crucial; esto generalmente viene en forma de una sección de descripción general de los documentos o una guía de inicio dedicada Esta descripción general debe cubrir detalles importantes como lo que realmente hace la API, cómo funciona a un alto nivel, los conceptos básicos de cualquier autenticación obligatoria y los idiomas compatibles / SDK disponibles. Un proyecto de demostración con el que el consumidor puede comenzar rápidamente es un buen toque. Cuando se trata de una presentación sólida, Braintree tiene una de las mejores.

Explicar cómo funciona la API y proporcionar datos de ejemplo es parte de la mayoría de la documentación, pero proporcionar una consola interactiva o un navegador API lleva las cosas al siguiente nivel. Una caja de arena de API brinda la oportunidad de ver cómo funciona todo y de examinar los datos. Idealmente, las cajas de arena proporcionan datos de muestra y reales (personales / autenticados).

Microsoft tiene una gran consola donde se proporcionan datos de muestra, pero también se puede usar una cuenta personal de Microsoft. Las diversas solicitudes de API se pueden realizar y modificar fácilmente, y los datos devueltos se imprimen en la pantalla en su totalidad. Los usuarios pueden comenzar de inmediato, lo cual es crucial. Trello también ofrece un navegador API interactivo, pero requiere una cuenta y un token autenticado para usarlo. Los pasos adicionales agregan fricción a la experiencia de la API.

La zona de pruebas API de Microsoft funciona con datos de usuarios reales.

Por último, un buen sitio explicará el uso previsto y las mejores prácticas de API . Deje en claro para qué sirve la API y para qué no. Este es el lugar para explicar por qué las cosas funcionan de la manera en que lo hacen y para transmitir al consumidor cómo integrar sin problemas su base de código existente con la API. Debe proporcionarse cualquier consejo para mejorar la experiencia del usuario final.

Mailchimp hace un buen trabajo con esto, brindando orientación sobre autenticación, manejo de errores / tolerancia a fallas y métodos de implementación para agilizar las cosas para el usuario.

Relacionado: Cómo los malos portales para desarrolladores acaban con las API

2. Descubra quién es su usuario desarrollador

Al desarrollar una API, tenga en cuenta al consumidor desarrollador. Siempre. La API está desarrollada para su uso, por lo que la pregunta que se debe hacer es "¿Quién es el usuario y qué es lo que más necesita?"

Las API utilizables añaden valor real para el consumidor de API . Tómese el tiempo para investigar quiénes son y comprender completamente sus necesidades y objetivos únicos. Si bien el consumidor de API puede ser el equipo que desarrolla la API si está destinada a uso interno, es probable que este no sea el caso de las API públicas.

Una vez que se identifica al usuario desarrollador, se pueden crear funciones para satisfacer sus necesidades principales. Aquí es donde Pareto entra en juego con su principio: la regla 80/20 . Básicamente, esta regla establece que el 20% del trabajo rinde el 80% de los resultados. ¿Cómo se aplica esto al desarrollo de API? Hable con el consumidor desarrollador objetivo, descubra exactamente qué problemas están tratando de resolver y comience por crear soluciones pequeñas y específicas.

Al crear lo que el consumidor de API necesita en lugar de que el equipo adivine qué es lo mejor, un poco de código puede tener un impacto masivo en términos de valor de API y usabilidad.

3. Practique la coherencia del diseño

La consistencia dentro de la API es crucial para reducir la fricción. Hace que las API sean más rápidas de recoger y seguir usando. ¿Qué significa la coherencia para el diseño de API? Hay algunas formas diferentes en que las API más utilizables lo abordan.

El primero es la coherencia en todo el mundo del desarrollo. Esto significa seguir prácticas comunes según sean relevantes, como usar códigos de servidor estándar en una API REST . Yendo un nivel más profundo, la API debe ser consistente con la industria dada Esto significa utilizar una terminología coherente y estudiar las API existentes para garantizar la compatibilidad en el enfoque.

La coherencia también se implementa en niveles inferiores . A medida que los microservicios continúan ganando popularidad, es cada vez más probable que las empresas ofrezcan múltiples API. Todas estas API deben ser coherentes en lo que respecta a aspectos como la autenticación , la estructura de nombres y los formatos de datos .

Una vez que un consumidor tiene un conocimiento de una API, debería ser muy fácil adquirir más. Esta misma coherencia se aplica también a la API individual. Cuanto más consistente sea una única API, especialmente a medida que crece, menos lectura de documentación y menos tiempo dedicado al aprendizaje se requiere del consumidor de API. Las API más fáciles de entender tienen más probabilidades de ganar al final del día.

4. Proporcione documentación utilizable

Si bien las mejores API son intuitivas y requieren una instrucción mínima, la documentación sigue siendo crucial. Realmente, la documentación puede hacer o deshacer toda la experiencia. Esto comienza con la UX del sitio de documentación en sí. No tiene que ser elegante de ninguna manera, pero al menos debe ser utilizable y legible. ¿No eres un diseñador natural? Involucre a uno o utilice uno de los muchos generadores de documentación automatizados .

El diseño del sitio puede tener un impacto en la legibilidad, pero no es el único componente; la documentación debe ser legible en primer lugar. En la medida de lo posible, apégate a un inglés sencillo y evita la jerga innecesaria. La base de usuarios no hablará el mismo idioma. Escriba simplemente para asegurarse de que la falta de capacidad para leer y comprender la documentación no sea una barrera de entrada.

Genere documentación usando estas herramientas.

Un componente crucial de un sitio de documentación sólido es una función de búsqueda . Si bien los nuevos consumidores de API pueden leer la documentación cronológicamente, es probable que los consumidores activos vengan en busca de una información específica. Los buenos resultados de búsqueda les brindan acceso directo a lo que necesiten, mientras que la navegación manual consume mucho tiempo y puede disuadir a los consumidores de API.

Por último (y esto se remonta a una buena primera impresión), asegúrese de que la documentación incluya ejemplos de código interactivo siempre que sea ​​posible, preferiblemente en varios idiomas. Permita que se modifiquen las consultas de API, por ejemplo, y muestre cómo se vería una respuesta de API real.

Lea también: 7 elementos sin los que ninguna documentación de API puede vivir

5. Utilice convenciones de nomenclatura inteligentes e intuitivas

Las convenciones de nomenclatura utilizadas en una API pueden tener un impacto amplio en lo que respecta al consumo de API y al uso continuo. Las convenciones de nomenclatura estandarizadas son una gran ayuda para la coherencia, una parte crucial de una buena experiencia de API.

Cuando se trata de nombrar, tenga en cuenta algunas cosas. Primero, KISS, o 'Keep It Simple Stupid'. Utilice los nombres más simples para los conceptos más comunes y guarde los nombres largos para las funciones únicas. Además, asegúrese de que los nombres sean intuitivos y estén relacionados con la funcionalidad.

En la medida de lo posible, la función de la llamada a la API debe quedar clara solo con el nombre. Por último, los nombres deben ser predecibles según la industria. Si cada herramienta o API relacionada llama a algo una manzana, no lo llame naranja.

6. Permitir que el consumidor de API controle los datos devueltos

Logotipo de GraphQL

Con el auge de herramientas como GraphQL , este concepto se está volviendo cada vez más común. Básicamente, el objetivo es brindar al consumidor de API la capacidad de acceder a todos los datos deseados con la menor cantidad posible de llamadas a la API . En última instancia, el consumidor sabe lo que quiere de la API. Facilitar la adquisición de los datos necesarios es una forma segura de mejorar las tasas de adopción de API, así como el número de usuarios en curso.

7. Asegúrese de que los errores sean significativos

Con demasiada frecuencia, las API devuelven mensajes de error muy básicos, sin una estructura útil ni ninguna información utilizable. Especialmente cuando un desarrollador implementa por primera vez una API, los errores pueden ocurrir con bastante frecuencia. Si no son útiles o no están claros, es desalentador para el usuario y esto puede generar altas tasas de abandono .

Para obtener más información sobre los errores, lea: Mejores prácticas para el manejo de errores de API

Para obtener más información sobre los errores, lea: Mejores prácticas para el manejo de errores de API

Para crear buenos mensajes de error , comience proporcionando una descripción del problema en texto plano . Mientras que las computadoras ejecutan las API y las aplicaciones, todavía hay una persona en el otro extremo de las cosas escribiendo el código. Debe haber algún tipo de explicación útil de por qué ocurre el error y, preferiblemente, un enlace a la documentación relevante o al artículo de soporte.

Hablando de eso, los mejores sitios de documentación proporcionan una sección dedicada a los errores. Idealmente, esto incluye una lista de todos los errores, así como información sobre por qué ocurrieron y la mejor manera de resolverlos.

Fundamentalmente, los errores también deberían poder recuperarse . Esto significa algunas cosas, como mensajes de error estructurados y con nombres consistentes. Los errores también necesitan opciones programáticas para acceder, además del texto centrado en las personas. Esto se hace más comúnmente a través de códigos de error , pero el enfoque debe determinarse en función de las necesidades de la API específica (y, por supuesto, incluirse en la documentación del error).

8. Admite varias bibliotecas y formatos de datos

Para la implementación, los consumidores de API quieren lo que quieren, y eso suele ser muchas cosas diferentes. En la medida de lo posible, los desarrolladores de API deben proporcionar bibliotecas oficiales en varios lenguajes y marcos.

No tener una biblioteca con soporte oficial en el idioma de su elección puede ser un gran obstáculo para los consumidores y evitará que muchos utilicen la API. Las bibliotecas desarrolladas por la comunidad son geniales, especialmente al principio del juego, pero nada supera a la oficial en términos de generar confianza.

La variedad también es importante para los datos de la API que se devuelven al usuario desarrollador. Si es posible, permítales seleccionar el formato (por ejemplo, XML, JSON o texto sin formato) que mejor se adapte a sus necesidades. Esto puede variar enormemente entre los diferentes casos de uso y es difícil de anticipar. Más variedad aquí hace que la API sea utilizable para muchos más consumidores.

9. Acepte siempre los comentarios

El consumidor de API sabe lo que necesita, así que ¿por qué no permitirle compartir sus opiniones fácilmente? Sus comentarios pueden resaltar errores comunes, conceptos mal entendidos y problemas frecuentes de implementación. También es muy útil para determinar una hoja de ruta para el desarrollo de API adicional. Cuando se trata de solicitar comentarios sobre nuevas funciones o cambios masivos de API, es mejor esperar un par de semanas. Los humanos pueden ser bastante resistentes al cambio (por ejemplo, el alboroto en cada nueva versión de iOS), pero después de unas semanas se adaptan y la retroalimentación se vuelve mucho más útil.

Los comentarios se pueden recopilar de muchas maneras: es importante comenzar a recopilar comentarios en lugar de posponer la implementación de un widget de comentarios complicado. El correo electrónico, las redes sociales, un formulario de contacto o un servicio dedicado con herramientas como encuestas son todos válidos. Cualquiera que sea el medio, colóquelo en un lugar destacado en el sitio de documentación y trate de permanecer abierto a todas las opiniones.

Relacionado: Consejos para crear una comunidad de desarrolladores

10. Realice pruebas de usuarios reales

Si bien esto puede parecer una quimera, especialmente para las nuevas empresas más pequeñas, nada señala problemas de API más rápido que las pruebas de usuario en vivo y en persona. Las grandes empresas pueden optar por la ruta del hackathon , y esta es una gran opción si los recursos lo permiten. Sin embargo, en realidad, la regla 80/20 se aplica mucho a las pruebas de usabilidad . Con solo traer de 3 a 5 usuarios desarrolladores con sobornos como un almuerzo gratis o un año gratis del servicio, se puede descubrir el 80% de los problemas en una tarde. El 20% restante es probablemente problemas bastante únicos que son bastante específicos de casos de uso individuales, no de la base de usuarios en su conjunto.

Al realizar las pruebas, proponga un par de desafíos para resolver con la API, en orden creciente de dificultad. Si los evaluadores encuentran problemas insuperables, haga que un desarrollador de API trabaje con ellos para comprender el problema y hablar sobre el proceso para resolverlo. Preferiblemente, estas conversaciones deben grabarse para que todo el equipo las revise. Después de la cantidad de tiempo especificada, revise la implementación. Solicite comentarios sobre desafíos, puntos fuertes, documentación, etc. También es útil hacer que el usuario desarrollador hable sobre su experiencia personal e impresiones en general, así como discutir cómo la API probada se compara con otras que podrían usar.

En conclusión

Para desarrollar una API verdaderamente sin fricciones, una que sea fácil de encontrar, adoptar y seguir utilizando, el consumidor de API es el componente clave . Solicite sus comentarios e intente ver desde su perspectiva mientras desarrolla la API. El usuario desarrollador sabe lo que necesita, así que dáselo y las posibilidades de éxito de la API mejorarán enormemente.

Publicar un comentario

0 Comentarios