Header Ads Widget

Ticker

6/recent/ticker-posts

Cómo administrar más de 1000 especificaciones a escala

 


Descubra cómo Target escaló su extenso catálogo de especificaciones de API corporativas

Muchos desarrolladores sienten pavor ante la idea de sentarse a escribir o mantener una especificación o documentación para su API. Eso no se debe a que no tengan confianza en sus habilidades de escritura (aunque eso puede ser un factor), sino a que están tan cerca del producto que les resulta difícil aislar lo que los lectores sabrán por instinto y lo que necesita explicación.

Ahora, imagina ese sentimiento de pavor multiplicado por 1000 veces. Eso es a lo que se enfrentó Jay Dreyer, ingeniero jefe de Target, cuando intentaba que la empresa… digamos, una amplia colección de API en buen estado.

En el evento ASC 2020, organizado por la Fundación Linux, Dreyer habló a través de Zoom sobre algunos de los desafíos que enfrentó (y aún enfrenta hoy), así como su uso de cosas como la especificación OpenAPI y las herramientas Swagger . Ya sea que tenga que administrar mil especificaciones de API o solo una, Dreyer tiene un gran consejo.

Especificación de API frente a documentación de API

Anteriormente hemos escrito sobre las ventajas que ofrece la documentación extensa y el diseño de API según las especificaciones. Pero, antes de profundizar demasiado en hablar sobre la gestión de un gran número de especificaciones, podría valer la pena mencionar las diferencias entre la documentación de API y las especificaciones de API.

En los términos más simples, una especificación podría explicar qué hace una API y cómo se vincula a otras API. La documentación se adentra en el meollo de la cuestión de cómo los desarrolladores pueden usar diferentes funciones, a menudo incluyendo casos de uso, y cómo llamar a esas funciones.

Si bien eso no significa necesariamente que administrar una gran cantidad de especificaciones sea fácil, vale la pena señalar que las especificaciones son un poco más sencillas ya que se basan en las mismas preguntas clave:

  • ¿Cómo está diseñada la API?
  • ¿Qué hace?
  • ¿Qué funciones facilita?

Administración de API lista para usar vs. Soluciones personalizadas

Dreyer describe cómo, en 2012, Target usaba Apigee para administrar sus API a través de una puerta de enlace API. "A medida que seguíamos agregando especificaciones, no teníamos un buen proceso implementado ... Teníamos especificaciones en todas partes y fue una especie de pesadilla".

Las especificaciones llegaron en diferentes formatos, por ejemplo, PDF, Microsoft Word, Google Docs, y no se actualizaron de manera efectiva después de subirlas al portal de desarrolladores de Apigee usando Drupal.

"En 2016", dijo Dreyer, "creamos nuestra propia plataforma (terminando la relación de Apigee) y la empresa se convirtió en una empresa más centrada en el desarrollador". Eso significó construir una puerta de enlace personalizada con un portal para desarrolladores de cosecha propia.

Su equipo también decidió documentar en una especificación Swagger. Parte de ese proceso significó documentar cosas como:

  • Quién es el propietario de la API
  • El estado del ciclo de vida de la API
  • Con quien hablar si algo se rompe
  • Cuánto tiempo ha estado disponible la API

Más allá de simplificar los procedimientos para tratar los problemas, el objetivo final era mejorar la coherencia en torno a cómo se catalogaban y administraban las API individuales.

Especificaciones y consistencia de API

"Inicialmente, dejamos que los equipos hicieran lo que quisieran", dijo Dreyer. Pero eso causó problemas.

Aunque adoptar un enfoque de no intervención se suele considerar una estrategia de gestión eficaz, especialmente cuando se intenta dejar que los equipos de desarrollo capacitados trabajen de la forma que mejor les convenga, puede complicar las cosas en el futuro.

Dreyer dijo que "se volvió casi imposible para nosotros ayudar a los equipos porque la forma en que estaban haciendo las cosas era muy diferente de una API a otra".
¿La solución? La implementación de estándares. Códigos de respuesta estándar y códigos de error estándar, por ejemplo, y el uso de JSON para las respuestas.

El uso de snake_casefue obligatorio, los verbos en los nombres de los puntos finales se prohibieron y se utilizaron sustantivos en plural para los nombres de las API y los puntos finales . En general, se recomiendan las mejores prácticas RESTful estándar .

Toda esta información se describió en una documentación interna completa y se almacenó junto con toda la otra información que esperaría de un buen portal para desarrolladores .

Automatización de procesos de especificación de API

En Target, cada API pasa por un proceso de incorporación que incluye una revisión formal de la especificación. Dreyer utiliza una herramienta personalizada llamada SpecVet, que actualmente no es de código abierto, en cualquier solicitud de extracción para identificar errores (categorizados como críticos o advertencias) en las especificaciones.

Llevar un elemento de automatización al proceso de evaluación es casi esencial cuando se intenta administrar más de 1,000 API. Sin embargo, probablemente no sea necesario si solo está tratando con un puñado de API o menos.

Además, Dreyer sugiere que sus intentos de crear coherencia han tenido el éxito suficiente para que la mayoría de las API aprueben este aspecto de la evaluación: "una vez que los equipos han pasado por el proceso una o dos veces, saben lo que estamos buscando".

También vale la pena señalar que no se pueden automatizar todos los aspectos del proceso de aprobación; no hay garantías de precisión, no hay forma de obligar a los equipos a actualizar sus especificaciones cuando se realizan cambios. Dreyer reconoce cómo, a veces, todavía tiene que perseguir especificaciones que ya están en producción.

El futuro de las especificaciones de API

La especificación OpenAPI , ahora en la versión 3.0.3, es casi con certeza la especificación más conocida que existe. Y, aunque ciertamente no es obligatorio, es algo que cada vez más desarrolladores de API están adoptando al publicar especificaciones.

En cuanto a la automatización de la producción de especificaciones API, todavía no lo hemos logrado. En realidad, ese es uno de los temas clave que Dreyer destaca en su charla, es decir, que la creación y verificación de especificaciones sigue siendo principalmente un proceso manual.

Sin embargo, eso no quiere decir que esto no pueda cambiar. Las listas de verificación, las muestras y las plantillas para la documentación de la API REST ya son bastante estándar, y Swagger ya ofrece una herramienta Codegen que puede generar stubs de servidor y SDK de cliente para una API definida con la especificación OpenAPI.

Herramientas como OpenAPI Generator y otras también generan documentación a partir de documentos OpenAPI . Quizás un producto similar que sea capaz de generar especificaciones con solo examinar una API no esté tan lejos después de todo.

Por ahora, el futuro de las especificaciones de API probablemente dependa en gran medida de cuán ampliamente se adopten las especificaciones de OpenAPI y otros estándares similares. Hemos estado cantando sus elogios por un tiempo, pero lea esta publicación si no está seguro de por dónde empezar.

Publicar un comentario

0 Comentarios