Header Ads Widget

Ticker

6/recent/ticker-posts

Estudio de caso: cómo Square automatiza la generación de SDK

 


Un kit de desarrollo de software, o SDK, es quizás una de las cosas más importantes que puede tener una API web. Los SDK son un sistema útil de bibliotecas y marcos para admitir la API, que a menudo incluyen documentación y otras pautas.

Lo que no se puede discutir es su importancia para los desarrolladores. Según Tristan Sokol de Square, "Si piensa en la experiencia del usuario final, los SDK son los puntos de contacto más importantes para las personas". Con este fin, la creación de material SDK adecuado es de vital importancia para el éxito de una API .

Un problema es que los SDK hechos a mano requieren mucho tiempo y esfuerzo de mantenimiento. Square adopta un enfoque alternativo; se generan de forma automática sus SDK utilizando una especificación API como única fuente de verdad .

En nuestra Cumbre de Austin en junio de 2018, Tristan describió en detalle el proceso de generación automática de SDK de Square. Entonces, en este artículo, revisamos ese proceso para ver cómo funciona. A medida que exploramos lo que están haciendo en Square para automatizar la generación de SDK, veremos si se podría aplicar un proceso similar para crear y mantener kits para desarrolladores en otras organizaciones.

Este artículo se inspiró en " Creación de SDK: hecho a mano frente a generado ", una presentación de Tristan Sokol en la Austin API Summit 2018. ¡El video se publicará en YouTube muy pronto!

Creación de la especificación OpenAPI

"Con la generación de SDK, una de las partes más importantes es su especificación".

Especificación de OpenAPI

Square usa la especificación OpenAPI como una única fuente de verdad para la generación de SDK.

Todo el sistema que usa Square para la generación de SDK se basa en una excelente especificación de API. En cada etapa, la especificación se utiliza como una fuente fundamental de verdad. Con tanto peso descansando únicamente en un solo punto, Square sabía que la solución de especificación debe ser algo estandarizado, eficiente y comprensible.

Con este fin, Square utiliza el estándar de especificación OpenAPI . En su caso, la especificación es un archivo JSON que define la URL, qué tipo de solicitudes HTTP se pueden realizar, qué información se debe proporcionar para tales solicitudes, qué información se debe esperar a cambio y otra información general. La especificación se divide en tres partes: información general / metadatos, rutas y modelos.

La información general incluye contenido como términos descriptivos de la licencia y restricciones, contactos a los que contactar en caso de problemas y más. Un equivalente aproximado serían los créditos iniciales de un guión de otro programa, en el que los desarrolladores normalmente proporcionaban campos comentados que detallaban el autor, la información de la licencia, etc.

A continuación, la especificación profundiza en las rutas . Las rutas son esencialmente los puntos finales proporcionados para la API y detalles sobre qué tipo de solicitud HTTP realizar y qué se puede esperar. Durante esta etapa, también se detalla información sobre el proceso de autorización, autenticación y más.

Finalmente, la especificación profundiza en modelos . Los modelos describen los objetos con los que interactúa la API y se utilizan principalmente para serializar la respuesta JSON de la API en objetos nativos para cada idioma admitido. Esta etapa proporciona gran parte de la funcionalidad co-interpretativa posterior, lo que permite que los SDK se generen en una variedad de idiomas de manera eficiente y efectiva.

Nuevamente, se debe enfatizar el valor de esta especificación: lo que esencialmente se está creando en esta etapa es una fuente de verdad única y universal , y debido a esto, la especificación debe ser correcta y estandarizada en todo momento.

Relacionado: ¿Qué idiomas debería admitir mi API?

Llenado de plantillas con Swagger Codegen

Los SDK se crean con Swagger Codegen

Con una sólida especificación implementada, Square comienza su proceso de automatización de la propia generación de SDK. Lo hace usando Swagger Codegen y aprovecha específicamente las plantillas que ofrece.

La especificación se alimenta en una serie de plantillas que toman cada parte de la especificación y separan los valores en los lugares apropiados de la plantilla de acuerdo con el lenguaje en cuestión y las funciones que se cubren. La plantilla usa un lenguaje llamado Moustache para hacer esto, definiendo cada parte de la plantilla y vinculándola a partes equivalentes en el archivo de especificación.

Durante esta etapa, también se generan comentarios de código , lo que permite la documentación incorporada y los comentarios de la base de código de la especificación. Esto es muy importante, ya que permite la documentación en línea y recursos fáciles de seguir para los desarrolladores que utilizan el SDK fuera del entorno nativo, como aquellos que utilizan un lenguaje diferente al de la implementación principal.

Swagger Codegen también hace un uso sustancial de archivos de configuración que describen aspectos del SDK que son parte de la capa de especificación. Esto agrega otro gran beneficio en el sentido de que los administradores de paquetes pueden serializar o transponer muy fácilmente los formatos e idiomas del SDK con plantillas adicionales.

Lea también: Prácticas recomendadas para la creación de SDK para API

Uso de Repos y Travis CI

Travis CI se utiliza para actualizar automáticamente los repositorios de SDK

Todo este proceso ocurre como parte de un proceso automatizado, por lo que ayuda a verlo dentro del contexto del sistema de repositorio subyacente. Cuando se modifica la base de código, se realiza una solicitud de extracción para actualizar el repositorio remoto en cuestión, lo que activa la instancia de Travis CI para que comience a ejecutarse.

Luego, Travis CI instala automáticamente Swagger Codegen y solicita un token de descifrado del usuario principal del repositorio. El token se utiliza para descifrar los cambios cargados, exponiéndolos a Travis CI. A partir de aquí, un script genera los SDK, recorriendo los idiomas, examinando la especificación, pegando los puntos de datos relevantes en las plantillas y, en última instancia, bombeando el SDK en cuestión. Desde aquí, Travis CI toma ese SDK y lo envía al repositorio secundario , que funciona como un repositorio de SDK además de la rama principal que aloja la base de código principal.

Un gran beneficio de este proceso automatizado es que Travis CI también realiza pruebas automáticas para garantizar que el SDK no interrumpa la funcionalidad principal o proporcione una experiencia de usuario cuantitativamente mala. Al automatizar todo el proceso y acoplar una especie de control de cuasi calidad, todo el envío de código se puede manejar rápidamente y con un mínimo de molestias para el cliente final afectado.

También le puede interesar: Utilice las pruebas automáticas de documentación de API para impulsar el crecimiento de API

Los búferes de protocolo alimentan la especificación

Si bien todo esto está muy bien, mantener la especificación actualizada puede ser complicado cuando hay tantos sistemas flotando, iterando y cambiando constantemente. Square maneja esto mediante el uso extensivo de búferes de protocolo . En esencia, un búfer de protocolo es una capa entre los servicios internos y la especificación. Este búfer ayuda a construir la especificación.

Cuando se realizan cambios , como un campo nuevo o una modificación a un campo existente, este cambio se envía al búfer de protocolo, que luego anota el cambio y lo registra automáticamente como parte de la especificación. Lo que esto significa fundamentalmente es que el búfer de protocolo está "alimentando" activamente la especificación.

Al hacer esto, la especificación, en teoría, nunca se desincronizará. Siempre que la especificación esté actualizada, el SDK también estará actualizado.

Pensamientos finales

Square es tanto un caso de estudio en la automatización de la generación de SDK como en el valor de la automatización en general. Con una planificación adecuada, una comprensión activa de los sistemas subyacentes y una licencia sensata de los sistemas que la impulsan, la automatización puede servir no solo como un caballo de batalla, llevando a cabo tareas rutinarias, sino como un sistema para habilitar mayores funciones.

Square es un gran ejemplo de automatización bien hecha. La generación de SDK a esta escala no sería posible sin la automatización, y es esta libertad la que facilita la puesta en marcha de servicios, recursos, bifurcaciones y más.

Con eso en mente, cabe señalar que todo esto depende de tener una única fuente verificable de verdad . En consecuencia, mantener todo lo más simple, correcto y actualizado posible es clave para que algo como esto funcione. Sin embargo, si puede equilibrarlo adecuadamente, es un enfoque muy poderoso y una gran herramienta para el desarrollo activo y consistente y la integración externa.

Publicar un comentario

0 Comentarios