Compartir:
){kind=small}
Alyssa is a writer and editor specializing in technology and the software development space. She lives in central California with her husband, kids, and three rescue dogs.
Desarrollo basado en OpenAPI en Nexmo
Tiempo de lectura: 4 minutos
En Nexmo, hemos adoptado un proceso de desarrollo basado en OpenAPI. He aquí por qué.
La historia nos ha enseñado que el desarrollo de software se ahoga bajo el peso de unas especificaciones sobrecargadas.
Andy Hunt, coautor del Manifiesto Ágil, cuenta la historia de un proyecto en el que trabajó en los años noventa. Tras dos años y medio y varios millones de dólares, el arquitecto del proyecto había elaborado una sala llena de diagramas UML, pero no se había desplegado ni una sola línea de código.
Hoy en día, equilibramos cuidadosamente la necesidad de especificaciones previas con la comprensión de que, a menudo, sólo escribiendo el propio código descubrimos la verdadera naturaleza del problema que estamos resolviendo.
Resulta, sin embargo, que el equilibrio entre las especificaciones y el descubrimiento es diferente para las API públicas de lo que es cuando estamos construyendo otros tipos de software. Y en Nexmo eso nos llevó a cambiar la forma en que desarrollamos nuevas API: lo primero que hacemos cuando desarrollamos un nuevo servicio es crear una especificación OpenAPI. Eso nos da beneficios en la experiencia del desarrollador, la legibilidad humana frente a la máquina, la automatización y mucho más.
Las API son contratos públicos. Cuando construimos y lanzamos algo como nuestra Messages APIestamos haciendo un trato con nuestros clientes: si haces la llamada X a la API con los datos Y, nuestra plataforma hará Z.
Eso hace que crear una API pública sea esencialmente lo mismo que crear un estándar. Piensa en SVG. Es un estándar para gráficos vectoriales. El estándar y las diversas implementaciones de ese estándar existen como cosas separadas. Si escribo una biblioteca que genera archivos SVG, no debería tener que preocuparme por los detalles de implementación de cualquier software que más tarde lea ese archivo.
Con demasiada frecuencia, las API están determinadas por la implementación subyacente, lo que Joel Spolsky denomina abstracciones con fugas-o por decisiones de diseño tomadas sobre la marcha. Empezar por crear una especificación OpenAPI significa que podemos tomar decisiones de diseño intencionadas que están un paso alejadas de los detalles de lo que ocurre por debajo. A su vez, esto conduce a una experiencia de desarrollo coherente e intuitiva.
Una ventaja inesperada es que la creación de especificaciones OpenAPI descubre posibles problemas de usabilidad. Hemos descubierto que si es difícil modelar una API en una especificación OpenAPI, eso suele significar que la propia API será difícil de usar. Esto nos ha empujado a replantearnos algunos diseños de API poco óptimos que, de otro modo, podrían haber llegado a producción.
Taylor Barnett de Stoplight.io describe las especificaciones OpenAPI como "un contrato de desarrollo, un puente entre equipos." Aunque los humanos escriben el código, las API actúan explícitamente como interfaces entre máquinas.
El desarrollo impulsado por las especificaciones OpenAPI convierte la API en mucho más que la interfaz entre dos fragmentos de código. Convierte la API en una fuente de acuerdos entre las personas. Los redactores técnicos pueden utilizarla para poner en marcha los esfuerzos de documentación, los defensores de los desarrolladores para explicarla a desarrolladores externos, los gestores de productos para mantenerla como fuente de verdad en relación con las capacidades de la API.
Como documentado por Kin Lanelas empresas publican cada vez más sus especificaciones OpenAPI en GitHub como declaración pública del diseño de una API. Con un documento, podemos hacer una declaración legible por máquinas y por humanos de cómo debe comportarse la API. A partir de ahí, los desarrolladores pueden ver cuál es el comportamiento esperado y razonar sobre las capacidades de la API.
Las especificaciones OpenAPI prometen permitir todo tipo de automatización. El potencial es poder generar automáticamente bibliotecas de clientes, puntos finales simulados, pruebas y documentación.
Screenshot of API
En Nexmo, estamos al principio de ese viaje. Hoy estamos autogenerando documentos de referencia de API y algunas pruebas. En particular, hemos encontrado que tener una especificación OpenAPI por adelantado ha hecho que sea más fácil crear pruebas de humo.
Nuestras especificaciones OpenAPI definen las entradas y salidas esperadas de la API, incluidos los mensajes de error. Podemos utilizar esas especificaciones para generar automáticamente pruebas de humo que proporcionen datos intencionadamente incorrectos y, a continuación, comprueben que se devuelve el mensaje de error esperado.
En última instancia, el mayor beneficio de todos es que al comenzar con una especificación OpenAPI, tenemos una única fuente de verdad. En lugar de tener diseños de API en diferentes formatos y en diferentes lugares (wikis, Google Docs, etc.), la especificación es ahora una parte estándar del proceso de desarrollo y se crea utilizando herramientas de desarrollo estándar.
Esa única especificación es una forma de decirnos a nosotros mismos y a nuestros colegas cuándo se ha completado el desarrollo y de decir a los desarrolladores externos qué pueden esperar. En cierto sentido, la especificación es la API y la implementación es solo eso.
Estamos al principio de nuestro viaje OpenAPI-first. Hasta ahora hemos probado el proceso con dos API.Redactar y Gestión de secretos-pero todas nuestras API tienen especificaciones OpenAPI públicas y completas, y tenemos previsto cambiar todo nuestro desarrollo al modelo spec-first.
De nuestro trabajo hasta ahora, estamos seguros de que esto conducirá a implementaciones de API de mayor calidad, ahorro de tiempo y una comprensión más profunda. Estamos impacientes por ver cómo mejorará la calidad de las API en todo el sector.