Header Ads Widget

Ticker

6/recent/ticker-posts

4 formas en que su especificación de API puede fallar (y qué hacer al respecto)

 


El uso de herramientas de especificación de API como la Especificación de OpenAPI ha revolucionado la forma en que diseñamos, construimos y administramos API. Además de ayudarnos a planificar la funcionalidad, generar documentación y ejecutar pruebas, una especificación puede cumplir la función más importante del contrato de API: definir con precisión lo que los consumidores pueden esperar de nuestra API.

Desafortunadamente, los formatos de especificación de API actuales tienen mucho espacio para la interpretación, dice el arquitecto de API de Microsoft Gareth Jones. Como resultado, los desarrolladores no siempre comprenden las expectativas del proveedor de API. Esto puede dar lugar a que algunas aplicaciones cliente se estropeen involuntariamente.

En este artículo, veremos cuatro áreas específicas en las que las especificaciones de la API pueden ser insuficientes y analizaremos cómo un poco de previsión puede ayudar a evitar cambios importantes.

Este artículo se basa en una presentación de Gareth Jones , arquitecto principal de API para Microsoft Education, en nuestra cumbre de API de Austin 2019 . Mira el video completo:

Problema n. ° 1: la cantidad de elementos

La mayoría de las API tienen al menos un punto final que solo devuelve un elemento la mayor parte del tiempo. Por ejemplo, considere una API bancaria con un accountspunto final. Es más probable que este punto final devuelva datos para una sola cuenta bancaria, ya que la mayoría de los clientes solo tienen una. A los desarrolladores les encantan los atajos, por lo que, dado el comportamiento normal de estos puntos finales, es posible que escriban su código para esperar un solo elemento. Luego, en los casos en los que hay más de un elemento, su código se rompe.

Verá el mismo fenómeno con la misma frecuencia con la paginación . Muy a menudo, los puntos finales devuelven menos de una página de datos, por lo que los desarrolladores codificarán para eso. Pero cuando llega una respuesta que abarca varias páginas, su código se romperá.

Según Gareth, este problema no es algo que las especificaciones de API como OAS siempre tengan en cuenta y, sin embargo, es un problema común. Parte de la razón de esto es que la documentación de la API a menudo muestra datos de respuesta de muestra demasiado simplificados. La falta de información allí anima a los desarrolladores a tomar atajos.

La solución para esto es simple: proporcione una mejor comunicación sobre la cantidad de elementos y páginas que los desarrolladores pueden esperar de cada punto final en su documentación . Con ese fin, incluya ejemplos de respuestas que reflejen todo el espectro de variabilidad de las respuestas API.

Relacionado: La diferencia entre documentación, especificación y definición de API

Problema n. ° 2: el tamaño de las cosas

Otro problema que probablemente no tenga en cuenta su especificación es el tamaño de cada respuesta. El tamaño se vuelve particularmente relevante en el caso de las API multimedia . Los desarrolladores pueden codificar fácilmente sus aplicaciones con imágenes de prueba de baja resolución, pero ¿podrán manejarlo cuando la API devuelva una imagen de alta resolución cien veces más grande?

Una vez más, resolver esto significa comunicar qué restricciones de tamaño tienen que codificar los desarrolladores en su documentación . Y dado que los desarrolladores no siempre leen los documentos, asegúrese de que los datos de muestra reflejen las cargas útiles más grandes con las que necesitarán codificar.

Problema n. ° 3: rendimiento

A los desarrolladores no les gustan las API lentas. El rendimiento lento de la API significa aplicaciones lentas y, cuando las implementaciones utilizan varias llamadas, el retraso aumenta para los usuarios finales.

Sin embargo, una actualización lenta de la API puede convertirse rápidamente en un cambio radical si sus consumidores confían en sus respuestas como parte de una secuencia, especialmente si los desarrolladores han tomado algún atajo . Claro, la mayoría de las aplicaciones estarán programadas para esperar una respuesta antes de continuar, pero ¿qué pasa si no lo hacen y su respuesta lenta evita que el código se ejecute correctamente?

Curiosamente, también puede romper las aplicaciones de los consumidores optimizando el rendimiento de su API. Es posible que los desarrolladores hayan escrito código en su contra después de una latencia esperada y, al acelerar su API, usted introduce una condición de carrera en su aplicación.

Solucione este problema estableciendo estándares de rendimiento para su API y siendo coherente con ellos . Si va a actualizar su API para que sea más rápido o más lento que los límites especificados en esos estándares, avise a los desarrolladores y modifique la versión del cambio.

Leer más: Aprenda a optimizar el rendimiento de la API

Problema n. ° 4: autorización

La autorización puede ser otra área problemática que su especificación no cubre. En particular, el tiempo durante el cual un token de acceso es válido parece una de esas cosas que podría cambiar sin romper nada ... ¿verdad?

¡No siempre! Los desarrolladores pueden haber tomado la ruta fácil al escribir su código: realizar flujos de trabajo más largos con un solo token de acceso, en lugar de pedir tokens de actualización. Pero, de nuevo, nunca lo necesitaron en el pasado, así que ¿por qué molestarse?

Para resolver este problema, fomente el uso de tokens de actualización en toda su documentación . Además, como se indicó anteriormente, advierta a sus desarrolladores antes de realizar cambios como este.

Más consejos para evitar estas roturas (y otras)

Además de las soluciones específicas descritas anteriormente, Gareth ve algunos principios que podrían ayudarnos a evitar romper las aplicaciones de nuestros consumidores en otras áreas. La solución ideal, por supuesto, es usar formatos de especificación que documenten estos detalles más finos o al menos agregar extensiones a nuestras herramientas de especificación existentes para hacerlo. Sin embargo, eso no es todo lo que podemos hacer.

Otra sugerencia que propone Gareth es incorporar la variabilidad (rápido, lento, grande, pequeño, un elemento, muchos elementos) en una API simulada dedicada. El simulacro resultante sería deliberadamente difícil de construir, pero los consumidores sabrían que sus aplicaciones se mantendrán en el mundo real si se mantienen firmes contra el simulacro. Como dice Gareth, preferimos que las aplicaciones fallen en el desarrollo y funcionen en producción que al revés.

Alternativamente, puede prestar más atención a los registros inmediatamente después de una nueva implementación. Además de buscar lo habitual (400 y 500), Gareth sugiere buscar cualquier señal de que pueda estar sucediendo algo inusual: más o menos llamadas de lo habitual, tamaños de paquetes más grandes o más pequeños y otros cambios similares.

Finalmente, Gareth sugiere que redefina su barra para cambios importantes. Si su prioridad es la continuidad del negocio, haga que su barra sea increíblemente sensible y tenga en cuenta los pequeños cambios en áreas no contratadas como las anteriores. Si prefiere moverse rápido y romper cosas, ¡hágalo!

Pensamientos finales

Una especificación de API a menudo cumple la función del contrato de API, pero no hay duda de que las herramientas de especificación actuales se quedan cortas en algunas áreas. En particular, cuestiones como la cantidad de elementos, el tamaño, la velocidad y la autorización tienden a estar mal definidos (si es que lo están) en las especificaciones actuales. Olvidarse de definirlos puede resultar fácilmente en cambios accidentales. Si bien las mejoras y extensiones para los formatos de especificación de hoy en día pueden resolver este problema en el futuro, Gareth tiene varias sugerencias alternativas: simulacros difíciles, seguimiento de registros y repensar cómo enfoca el concepto de un cambio radical.

Publicar un comentario

0 Comentarios