Header Ads Widget

Ticker

6/recent/ticker-posts

Los tres principios de un excelente diseño de API

 


Todos sabemos que usar una API bien diseñada es extremadamente gratificante, mientras que usar una API mal diseñada puede ser lo suficientemente frustrante como para que nos demos por vencidos. Sin embargo, cuando nos esforzamos por construir las API mejor diseñadas posibles, tendemos a tropezarnos de inmediato preguntándonos:  ¿qué hace que el diseño de una API sea bueno o malo?

Para Arnaud Lauret, creador del API Stylebook y autor de The Design of Everyday Las API , las API y los objetos cotidianos tienen mucho en común cuando se trata de su diseño . Nos contó más sobre estas similitudes y sus otros principios de buen diseño de API en nuestra Cumbre de plataforma , ¡y nos brindó muchos ejemplos divertidos en el camino! Hoy, compartiremos esos mismos principios con usted.

Los tres principios de Arnaud

El buen diseño se puede dividir en tres aspectos principales , dice Arnaud, y esos son el propósito , la usabilidad y las limitaciones . Si tiene en cuenta cada principio al crear una API, o cualquier objeto doméstico para el caso, obtendrá un resultado fantástico.

Profundicemos en cada uno de estos principios de diseño, analizando cómo funcionan y cómo podemos optimizarlos.

1. Propósito

“¡He aquí el Kitchen Radar, un nuevo dispositivo para calentar alimentos que utiliza tecnología de grado militar para reducir el tiempo de horneado de pasteles de cuarenta minutos a ocho! Simplemente mezcle sus ingredientes húmedos, caliente por unos minutos, agregue los ingredientes secos y caliente por unos minutos más. Incluso puede descongelar alimentos en el radar de la cocina, pero tendrá que presionar el botón único de la interfaz de manera intermitente (dejando el dispositivo encendido durante siete segundos y apagado durante el mismo tiempo) para hacerlo ".

La divertida analogía de Arnaud es, por supuesto, burlarse de un microondas hipotético con un solo botón de encendido, lo que claramente sería una mala elección de diseño. Una interfaz de un solo botón expone el funcionamiento interno del dispositivo (que solo es capaz de calentar alimentos de manera intermitente) y no tiene ninguna preocupación por el propósito final del producto.

Compare eso con un horno microondas con regulador, donde pueda heat food at <power> for <time>, y verá que un buen diseño presta atención al propósito del producto y minimiza cualquiera de las limitaciones internas que podrían interponerse en el camino de ese propósito.

El resultado es para la misma implementación de calentamiento de alimentos, necesitaría 20 líneas de código para usar el radar de cocina (que consiste en un gran bucle que enciende y apaga el dispositivo a intervalos proporcionales a la potencia), pero solo uno para usar el microondas.

La lección para los profesionales de API aquí es crear un propósito en el diseño. Comprenda las necesidades del desarrollador final , estructura su servicio con suficientes métodos para la mayoría de las llamadas requeridas y haga que todos los parámetros sean detectables y estén claramente definidos en la documentación de la API .

"Una API es, ante todo, una interfaz para las personas"

2: usabilidad

Una vez que el propósito de su API está fuera del camino, la usabilidad es el siguiente criterio de diseño a considerar. Arnaud dice que la usabilidad en sí puede dividirse en tres categorías: representaciones , interacciones y flujos . Todos estos juntos contribuyen en última instancia a un diseño predecible .

Usabilidad en representaciones

Todas las representaciones en su API deben ser intuitivas , lo que quiere decir que todos los usuarios deben poder comprender todos los nombres y otros detalles a primera vista.

Imagina que un despertador te muestra una cuenta regresiva de los segundos hasta que suena, lo que no es una representación muy útil o utilizable. Compare eso con un reloj de alarma que le muestra la hora exacta a la que sonará; ahora es una información relevante para el usuario.

Para emular esta idea en el diseño de su API, asegúrese de que las representaciones (especialmente los nombres) sean lo más coherentes, sencillas y relevantes posible . Si sus usuarios necesitan acceso a las identificaciones de los clientes, llámelos exactamente así customer_ids, y no use otros nombres para lo mismo.

Usabilidad en interacciones

A continuación, en el tema de la usabilidad: haga que las interacciones con su API sean lo más utilizables posible . Por supuesto, también hay una metáfora para eso.

Con algunas lavadoras, puede elegir la temperatura, la velocidad, el tamaño de la carga y más. Con otros, simplemente elige un programa y la máquina se encarga del resto. Para algo tan mundano como lavar un par de jeans, ¿cuál preferirías tener?

Esta usabilidad en las interacciones que realiza con un producto se trata de tener pocas entradas sencillas (y permitir que el código extrapole cualquier otro parámetro). Igual de importante es proporcionar comentarios valiosos durante todo el proceso.

Al igual que una lavadora puede decirle que "LA PUERTA NO ESTÁ CERRADA" en lugar de simplemente negarse a funcionar, una API que devuelve valiosos comentarios de error está muy por delante de una API que se niega a funcionar y no ofrece ninguna razón.

Por último, no te olvides de los comentarios positivos: es útil saber que tu ciclo de lavado ha comenzado y que tendrás tus jeans listos en 40 minutos, y los jeans de los desarrolladores también son importantes.

“Diseñe interacciones API sencillas. Solicite únicamente entradas mínimas y sencillas. Evite solicitar miles de parámetros ... "

Usabilidad en flujos

Finalmente, está la usabilidad de los flujos. Un flujo de API utilizable hace que los procesos sean lo más fluidos posible , para que los usuarios puedan obtener el resultado deseado de forma más rápida y sencilla.

Considere un ascensor con solo un botón afuera y sin pantallas. Para ir de un piso a otro, debe llamar al ascensor, elegir su piso cuando esté adentro, ir a donde se dirija y luego subirlo a su piso.

Simplemente agregando un símbolo ARRIBA o ABAJO al elevador, los usuarios pueden tomar el elevador en su dirección. Puede ir un paso más allá e introducir dos botones fuera del ascensor, lo que permite a los usuarios elegir en qué dirección se dirigen desde el principio.

En el diseño de API, esto significa mejorar la retroalimentación, minimizar errores y agregar acciones. Todas estas cosas le permiten obtener el resultado deseado de forma más rápida y sencilla.

El buen diseño es predecible

El juego final para la usabilidad de la API es una API predecible ; si los usuarios saben qué esperar de su API, es mucho menos probable que tengan dificultades para usarla. Puede dividir el diseño predecible en tres elementos:

  • Consistente: cree una API que sea coherente consigo misma, en toda la organización y con los estándares y prácticas globales. Esto facilita la interacción con su API.
  • Adaptable: permita a los usuarios adaptar su API de la manera que más les convenga. Ofrece funciones de paginación, clasificación y filtro que permiten a los usuarios elegir sus representaciones (negociación de contenido) e internacionalizar todo, desde idiomas hasta monedas ... ¡pero no lo hagas demasiado complicado!
  • Detectable: ayude a los usuarios a encontrar la funcionalidad que necesitan y aprenda el diseño de la API desde adentro hacia afuera. Esto incluye metadatos para la paginación y el uso máximo de protocolos subyacentes, como el uso de Aprobar para indicar métodos HTTP aceptables.

Restricciones

Por último, para un diseño de API eficaz,  imponga restricciones si le permiten mejorar su producto . Al igual que un reloj de buceo hará sacrificios en su diseño para hacerlo más adecuado para el buceo, debe restringir voluntariamente su API si eso le permite adaptarlo mejor al propósito final.

Si la latencia es un problema, cree API de grano más grueso que no necesitan ser llamadas tanto. De manera similar, puede limitar la frecuencia de las llamadas a la API u ofrecer webhooks que brinden actualizaciones a los usuarios solo cuando sea necesario.

Aquí, no es solo el usuario lo que importa. Si puede hacer compromisos de diseño razonables para mejorar la entrega del producto desde su extremo, como limitar las llamadas a la API para mejorar la escalabilidad u ofrecer retornos asincrónicos para mejorar el rendimiento, vale la pena considerarlo.

“Centrarse en la usabilidad es algo muy bueno. Pero, no debe hacerse sin olvidar que el diseño debe estar restringido ".

Empatía y contexto

Para obtener más información de Arnaud Lauret , veterano de las API nórdicas y técnico de API , lea su libro The Design of Everyday API .

Un buen diseño de API es como un buen diseño de producto . Dos cosas importan por encima de todo: la empatía y el contexto .

La empatía representa una comprensión de las necesidades y limitaciones del usuario y se enfocaría en concretar el propósito de su API o mejorar la usabilidad, mientras que el contexto representa una comprensión de cómo el producto está preparado para brindar un cierto beneficio, que incluiría todo: propósito, usabilidad y limitaciones.

Publicar un comentario

0 Comentarios