Header Ads Widget

Ticker

6/recent/ticker-posts

4 áreas de coherencia para una gran experiencia de desarrollador



Pocas cosas dañan tanto a una API como la inconsistencia. La inconsistencia dentro de un ecosistema de API puede frustrar y confundir incluso a los usuarios avanzados más experimentados, creando un ciclo perpetuo de llamadas fallidas y suposiciones incorrectas.

Si bien rara vez se considera un problema propio, a menudo se agrupa por tipo (como códigos de error poco claros), la realidad es que la inconsistencia crea más inconsistencia; si un aspecto de una API sufre esto, es probable que el resto también lo haga.

A continuación se muestran algunas áreas específicas de diseño de API donde la inconsistencia es común. Consideraremos las implicaciones de cosas como la nomenclatura inconsistente de los puntos finales, los códigos de error variables y la documentación irregular, y veremos cómo podemos, en cambio, construir experiencias de desarrollo más intuitivas.

1. Nomenclatura y coherencia de los puntos finales

Uno de los problemas de coherencia más comunes en muchas instancias de API modernas también resulta ser el más amplio: la coherencia de nombres . Los problemas de nombres cubren algunos dominios, pero la inconsistencia en todos los ámbitos puede causar problemas importantes, independientemente de dónde viva esa inconsistencia para una amplia gama de usuarios. Echemos un vistazo a dos posibles dominios donde esta inconsistencia puede ser un problema.

Claridad

Para una API pública , uno de los objetivos de desarrollo debería ser que la API se entienda fácilmente. Si bien esta comprensión generalmente se obtiene a través de una amplia documentación u otros esfuerzos educativos, la denominación de los puntos finales a menudo se pasa por alto como una oportunidad profunda para expresar el propósito y la intención. La forma en que se nombran los endpoints y lo descriptivos que son puede afectar significativamente la forma en que el usuario promedio entiende con qué se interactúan.

Imagine que está desarrollando una API que le proporciona información meteorológica a un usuario de forma remota. Al considerar una colección de puntos finales, imagine dos extremos. Por un lado, tenemos una versión oscura:

https://weatherapi.nordicapis.com/aqi10
https://weatherapi.nordicapis.com/tmplcl
https://weatherapi.nordicapis.com/usrlclctyid

Estos puntos finales son bastante incomprensibles. Pueden representar una abreviatura de los nombres de funciones internas, pero el desarrollador externo promedio probablemente no tenga ni idea de lo que hacen. Quizás puedan inferir una función posible, pero no todo el propósito.

En cambio, cambiemos el nombre de estos puntos finales para que sean más comprensibles:

https://weatherapi.nordicapis.com/airqualityindex
https://weatherapi.nordicapis.com/localtemperature
https://weatherapi.nordicapis.com/setusercity 

Para el usuario final promedio, este cambio podría ser tan monumental que desbloquea la comprensión de toda la API, aumentando las capacidades de autoservicio.

Caja

Además, si se utiliza un estilo de carcasa, debe ser coherente en todos los puntos finales. CamelCase (en el que cada palabra nueva está en mayúscula, por ejemplo, AirQualityIndexairQualityIndex), Snake Case (donde los guiones bajos reemplazan los espacios, por ejemplo, Air_Quality_Index) y otros enfoques son aceptables. Aún así, debe considerarse una mejor práctica mantener este estilo consistente. Por ejemplo, si un extremo lo es AirQualityIndex, no debería tener también una instancia de set_User-CityPequeñas variaciones como esta, sobre la amplitud de un servicio, pueden resultar en una mayor complejidad y menos comprensión.

Exactitud

Relacionada con la claridad del punto final está la precisión relativa de cada punto final. No es suficiente asegurarse de que el nombre del punto final sea coherente; también debe asegurarse de que hace lo que dice que hace.

Las incompatibilidades a menudo surgen después de múltiples revisiones y variaciones en el código base central, especialmente si es antiguo o depende de otras bibliotecas. Por ejemplo, ampliemos el ejemplo de API meteorológico imaginado. Nuestros usuarios solicitan más funciones. Una función tiene que ver con la integración en aplicaciones de calendario para proporcionar una instantánea del clima de la semana junto con las actividades programadas. A medida que se desarrolla, descubre que uno de los puntos finales,, de hecho, no muestra el clima en una agrupación para la semana, pero proporciona la temperatura y la precipitación semanales promedio.https://weatherapi.nordicapis.com/weeklyweather

Un nombre tan poco claro puede causar problemas importantes tanto para los desarrolladores como para los usuarios. Para los desarrolladores, especialmente aquellos que no trabajaron en el código base central, las suposiciones basadas en la funcionalidad nombrada pueden resultar en aplicaciones no funcionales. Algunos puntos finales pueden ser relativamente comprensibles, como el ejemplo anterior, mientras que otros pueden ser menos comprensibles. Algo como podría implicar tantas funciones detrás (hora local, hora específica de GMT, hora regional, etc.) que simplemente no está claro para ser útil.https://weatherapi.nordicapis.com/time

2. Paradigma de diseño de API

El estilo de diseño de API elegido por un proveedor es esencial, pero ser coherente con él es aún más crítico. No es extraño que una API adopte un paradigma basado en la solución de jure, pero siga mal esa elección. Las API que afirman ser RESTful a veces no siguen un inquilino principal de diseño RESTful, las API GraphQL pueden no permitir solicitudes verdaderamente transformadoras de los usuarios, etc.

Esto no es solo cierto para los desajustes de paradigmas. A veces se sigue el paradigma, pero el ecosistema de API interno es incoherente o confuso. Una API puede enviar otras solicitudes a otras API internas y, a menudo, estas API pueden estar agrupadas de manera extraña (por ejemplo, una API que maneja la transformación de medios también puede administrar cuentas de usuario).

En un paradigma RESTful, no solo es suficiente ser RESTful, también debe ser RESTful y coherente en todas las API.

También es importante saber cuándo no ser RESTful , cuándo aprovechar otras opciones y, lo que es más importante, cuándo separar una API monolítica en microservicios (o viceversa). En última instancia, no importa qué paradigma utilice: si está DESCANSADO, sea DESCANSO. Si usa SOAP , siga SOAP, pero sobre todo, sea coherente. La utilización de una guía de estilo interna (como las del API Stylebook ) puede ayudar a garantizar y hacer cumplir esta coherencia. Si vas a usar una guía como esta, debes insistir en ella y usarla. Nuevamente, sobre todo, sea consistente.

3. Manejo de errores

Un punto de claridad que a menudo se pasa por alto es el manejo de errores . Con demasiada frecuencia, el manejo de errores se resuelve sirviendo códigos de error generales sin información adicional. ¿Cuántas veces un servicio ha devuelto un error que simplemente dice "lo siento, este recurso no se encuentra"? Para el usuario final, esta experiencia no solo es ineficaz; es frustrante.

Los errores deben manejarse de manera consistente, dada una forma y función específicas. Uno de los mejores recursos para estandarizar el manejo de errores es usar códigos de estado HTTP estándar . Esta es una gran solución, ya que cada tipo de código de error está delineado y es comprensible simplemente al saber en qué categoría pertenecen estos códigos. Los códigos estándar se indican a continuación:

  • 1xx : estos códigos entregan información, generalmente para confirmar la recepción de la solicitud.
  • 2xx - 200 - este espectro de códigos indica que una solicitud fue recibida, comprendida y aceptada.
  • 3xx : esta banda de códigos señala una condición de redirección y puede ser un indicio de que la solicitud inicial, aunque una vez precisa, ya no es el método adecuado.
  • 4xx : estos indican errores del cliente, lo que indica una sintaxis incorrecta o algún otro error.
  • 5xx : estos indican errores del servidor de una solicitud válida.

Estandarizar detrás de estos rangos de código y entregar los códigos correctos cada vez de manera consistente puede aumentar drásticamente la precisión, eficacia y funcionalidad de la API y el flujo de usuarios promedio. El aspecto clave aquí es garantizar la coherencia: los errores del usuario deben estar centrados en el cliente, los errores del servidor deben estar en el rango 5xx, etc.

4. Documentación

La documentación nunca debe considerarse una ocurrencia tardía; la coherencia es extremadamente importante para la calidad de la documentación . Entonces, ¿qué significa esto en la práctica?

Primero, asegúrese de que su documentación sea precisa . En un nivel básico, la documentación debe reflejar las funciones, los puntos finales y las facetas reales de la API con gran detalle. La documentación siempre debe coincidir con la producción; es esta coherencia la que se presta a la precisión y, por lo tanto, a una buena documentación.

En segundo lugar, la navegación es un aspecto vital que a menudo se pasa por alto. No solo es suficiente tener documentación precisa , los desarrolladores deben poder navegar por ella. Una forma de aumentar la coherencia aquí es pensar en su documentación desde un punto de vista científico. Desglose todo primero por temas, luego por funciones, variaciones y finalmente ejemplos. La estructura específica no tiene por qué ser exacta; lo más importante es que si adopta un formato, cúmplalo.

Finalmente, el contenido debe ser eficiente . Piense en el consumidor desarrollador medio : ¿tiene tiempo para leer durante una hora para comprender una función? Por supuesto que no, dependen de la brevedad, los ejemplos y la eficacia. Sea breve, conciso y preciso.

Conclusión

La inconsistencia en una API puede generar ineficiencia, confusión y fallas. Con todo esto en mente, la solución es simple: sea coherente. Incluso si adopta sus propios estándares de estilo, nombres, códigos de error, etc., sea uniforme en toda su plataforma de desarrollo.

Siempre que todo se haga de manera coherente, incluso las soluciones patentadas se pueden aprender y comprender rápidamente dentro del contexto del resto del trabajo. Mientras exista alguna inconsistencia, la API siempre carecerá de aclaraciones, lo que disminuye la usabilidad y las capacidades de autoservicio.

¿Cree que estamos exagerando la importancia de la coherencia? ¿Existe otra faceta que posiblemente sea más importante? ¡Háganos saber en los comentarios a continuación!

Publicar un comentario

0 Comentarios