Header Ads Widget

Ticker

6/recent/ticker-posts

5 formas en que la especificación OpenAPI estimula la agilidad de la API


 El ciclo de vida de la API es un tema de mucha discusión, y con razón. El espacio API es ágil, cambia constantemente y sus participantes deben satisfacer continuamente el caleidoscopio cambiante de necesidades y demandas de los usuarios.

Entonces, muchos consideran que acelerar y asegurar este ciclo de vida es el Santo Grial. Poder aprovechar las especificaciones de API probadas es un método poderoso, ya que el uso adecuado de las especificaciones abre un campo completamente nuevo para los desarrolladores. Ya sea que se trate de documentación eficiente y automatizada , usabilidad mejorada y experiencia de desarrollador con sandboxing dinámico o disminución de la velocidad de comercialización a través de una iteración más rápida , los beneficios no pueden ser exagerados.

Hoy veremos una maravillosa solución para ayudar a alcanzar este noble objetivo: la especificación OpenAPI . Hablaremos un poco sobre qué es en realidad y cómo puede permitir un desarrollo de API más rápido y seguro.

Esta publicación se inspiró en una charla de Arnaud Lauret en la Cumbre de la Plataforma 2016:

¿Qué es la especificación OpenAPI?

La especificación OpenAPI es una implementación de especificación y marco diseñada para crear archivos de interfaz legibles por máquina para describir, producir, consumir y visualizar servicios web en una arquitectura RESTful. Como describe Lauret, los casos de uso son numerosos:

“El universo de especificaciones de OpenAPI se extiende mucho más allá de la documentación generada. Es ilimitado. La especificación OpenAPI se puede utilizar para acelerar y asegurar la creación y evolución de API ".

Antes de que existiera OpenAPI, existía Swagger . Swagger se diseñó originalmente para su uso en el servicio de descubrimiento de palabras de Wordnik, un servicio web que se promocionaba para "encontrar significado en las palabras". Swagger se diseñó luego bajo esta misma pauta, aunque con una ligera desviación, para "encontrar significado en las API".

En 2015 , el proveedor de API SmartBear adquirió el marco Swagger de código abierto y comenzó a expandirlo fuera de los límites del caso de uso de Wordnik. En 2015, SmartBear ayudó a crear una nueva organización bajo el estandarte de la Fundación Linux llamada Open API Initiative , trabajando con Google, IBM y Microsoft para crear nuevas herramientas y soluciones. Como parte de sus esfuerzos, lanzaron la Especificación Swagger al grupo, denominándola Especificación OpenAPI. Cabe señalar que las herramientas en torno a la especificación aún conservan la marca Swagger (Swagger Editor, UI, Codegen, etc.). En el momento de escribir este artículo, la especificación OpenAPI se encuentra en una versión 2 estable con una  versión 3.0  en estado de borrador.

Relacionado: Definiciones de API estándar desmitificadas

¿Por qué la especificación OpenAPI?

La especificación OpenAPI tiene algunas características realmente especiales que la hacen tan bien recibida en el mundo de las API. En primer lugar, OpenAPI es independiente del idioma . A diferencia de otras soluciones, esta especificación no tiene preferencia de idioma y puede funcionar en cualquier idioma con instrucción menor.

Otro gran beneficio de la especificación OpenAPI es que, como resultado de su dependencia específica de la especificación de recursos declarativos, los clientes tienen una visión de la funcionalidad mucho más amplia, sólida y holística . En lugar de depender del código de servidor restringido o la documentación, la Especificación OpenAPI, de muchas maneras, se describe a sí misma .

Envuelto en la Especificación OpenAPI está Swagger-Codegen , una pieza de tecnología Swagger que utiliza un motor impulsado por plantillas para generar documentación , stubs fundamentales del servidor y clientes.

Por muchas razones, OpenAPI a menudo se considera la mejor solución hasta la fecha para el desarrollo de API. Con esto en mente, ¿cómo nos ayuda específicamente a alcanzar nuestra meta?

Solidez API

"La rapidez de la API es probablemente lo que todos los proveedores de API pretenden hacer: poder entregar una API de forma rápida pero segura".

Lauret define la rapidez de la API como acelerar el desarrollo de una API y sus recursos mientras se mantiene la seguridad y el control de calidad. Básicamente, estás apuntando a lo mejor de ambos mundos y, como parte de eso, estás aceptando algunas limitaciones.

En el ciclo de vida del desarrollo clásico, usted juega un juego de equilibrio: sacrifica la calidad por la velocidad del mercado y pierde algo de velocidad cuando se concentra en asegurar los recursos. Aunque no todos los proyectos tendrán las mismas dificultades, la lentitud y la metódica suelen contrarrestar la rapidez y la innovación. Como dijo una vez Mark Zuckerberg, " muévete rápido y rompe cosas ".

Afortunadamente, la especificación OpenAPI elimina muchas de las partes de "romper cosas" de ese lema y se centra más en "moverse rápido". Aquí hay 5 formas en que lo hace.

1: Diseño y enfoque adecuados

Cualquier buen ingeniero puede decirle que las estructuras no fallan por el último ladrillo, fallan por el primero. Si comienza con una base inestable o una base sólida, se derrumbará, y lo mismo ocurre con una API.

La especificación OpenAPI proporciona quizás una de las bases más sólidas sobre las que se puede construir una API. No solo proporciona herramientas o enfoques, sino que también proporciona un enfoque de diseño adecuado sobre cómo interactuará con su API.

“Un comienzo es un momento muy delicado, especialmente para una API. Ya sea que una API sea interna o externa, su diseño es crucial. Un mal diseño puede provocar un desastre total. Puede matar proyectos e incluso empresas ".

Quizás el ejemplo más poderoso de cómo lo hace la Especificación OpenAPI es la sincronización del código fuente y las bibliotecas cliente . No sincronizar estos elementos puede resultar en conjuntos de códigos divergentes e interacciones horribles para el consumidor.

Por otro lado, adoptar una metodología adecuada para garantizar que el contenido esté sincronizado correctamente puede mejorar la funcionalidad. La mayor parte de todo esto es que las tres formas principales en que se realiza esta generación de especificaciones: Codegen, generación automática (swagger-node-express y swagger-play) y manualmente, son completamente adaptables a funcionalidades API específicas y a la estética del diseño.

2: Documentación y descripción completas

SwaggerUI, un elemento de OpenAPI, es sumamente poderoso y capaz cuando se trata de generar documentación descriptiva . Debido al origen de la especificación de OpenAPI, específicamente Swagger , el principal punto de venta de la “documentación precisa y fácil” que vino con Swagger también se comparte dentro de OpenAPI. Como describe Lauret:

“La especificación OpenAPI es capaz de describir una API de manera fácil y eficiente. Cada aspecto se puede describir fácilmente en un documento simple pero estructurado ".

Ese tampoco es el final: la especificación OpenAPI está abierta por diseño, lo que ha dado lugar a algunos competidores serios para la funcionalidad que refleja la de SwaggerUI. Por ejemplo, APIs.guru ha lanzado su solución ReDoc como un sistema alternativo.

Para otras soluciones de generación de documentos, consulte la Guía definitiva para más de 30 soluciones de documentación de API

Ese es el verdadero poder aquí. Cualquier servicio de documentación que se precie hará el trabajo, pero la Especificación OpenAPI se basa específicamente en la idea de abrir una API a múltiples soluciones, lenguajes y enfoques en un esfuerzo por alcanzar la mejor solución posible para cualquier permutación dada .

3: Pruebas e iteraciones rápidas

La especificación OpenAPI utiliza una especificación de recursos declarativa y, como parte de esto, permite una fácil exploración de la API sin acceso al código del servidor o sin comprender la implementación del servidor.

Esto significa que, a diferencia de otras soluciones en las que el desarrollador tiene una gran caja de arena, pero el usuario promedio está restringido, la API se puede colocar en una caja de arena de una manera que permite tanto a los desarrolladores como a los no desarrolladores comprender y explorar en una caja de arena interactiva.

Todo esto se hace a través de esa implementación mágica llamada SwaggerUI. SwaggerUI lee la descripción de la API que se indica como parte de la especificación OpenAPI y la presenta como una página web.

Si bien esto es excelente desde el punto de vista del consumidor, el beneficio real aquí está en las pruebas y la iteración . Al poder probar y modificar activamente el contenido de la API durante el desarrollo en un entorno de espacio aislado, los puntos finales se pueden probar con cualquier permutación, el acceso a los recursos se puede probar en una multitud de entornos y la API se puede probar en interacciones con otras API.

Esto ayuda drásticamente en la iteración y permite realizar pruebas dinámicas y verdaderamente rápidas con un mínimo de tiempo extra.

4: Tiempo de comercialización más corto (más seguro)

Debido a la drástica reducción mencionada anteriormente en los recursos y la dedicación de tiempo para las pruebas y la iteración, esto también naturalmente resulta en una disminución en el tiempo de comercialización . Al tomar menos tiempo para iterar y usar menos recursos entre las revisiones iniciales, esto da como resultado un ciclo mucho más rápido a medida que las características se incorporan al conjunto de códigos principal de forma dinámica.

Una nota al margen clave aquí es que esto también aumenta drásticamente el nivel de seguridad de la API. Debido a que el desarrollador puede probar e iterar con relativa facilidad y rapidez, los problemas en la base del código y sus interacciones se descubren antes en las pruebas, y los errores se adjuntan directamente a los recursos indicados.

Imagina construir un motor. Al juntar las piezas, debe probar cada elemento y, al agregar una pieza nueva, debe probar el motor como un todo. Ahora imagine la misma situación, pero con una supercomputadora que permite probar cada pieza individual sin importar qué tan profunda sea la pieza, qué tan rodeada de otras piezas esté y qué tan básica o auxiliar de la funcionalidad general sea.

Esto es funcionalmente lo que le permite hacer la Especificación OpenAPI: probar cualquier cosa de forma dinámica y con poca sobrecarga y tiempo entre pruebas.

Relacionado: Cómo hacer una API ágil

5: Traducción y legibilidad humana y mecánica

"La especificación OpenAPI también se puede utilizar para crear documentación legible por humanos".

La especificación OpenAPI es una piedra de Rosetta para el espacio API. Mientras que otras soluciones generan datos centrados en la máquina con fines de funcionalidad y luego derivan de esta documentación y especificación legible por humanos (o viceversa), la especificación de OpenAPI comienza desde una posición diferente: un lenguaje progenitor del que se deriva el resto del contenido.

Al funcionar como una especificación que describe la API, la especificación de OpenAPI puede derivar contenido legible tanto por máquinas como por humanos de una manera mejor y más completa. Este enfoque llevó a Swagger a convertirse en un nombre familiar en el espacio API, y continúa influyendo en las tendencias de documentación hasta el día de hoy.

La especificación OpenAPI aprovecha sus poderes para crear el contenido más completo y útil en formato legible tanto por máquina como por humanos; una habilidad importante que simplemente no se puede exagerar.

Conclusión: OpenAPI permite un ciclo de vida de API ágil

Como desarrolladores, proveedores de API y evangelistas, el mayor problema al que nos enfrentamos en esta industria es moverse a una velocidad lo suficientemente rápida como para iterar e innovar, mientras aseguramos los recursos de los que dependen nuestros consumidores. No es una tarea fácil: muchos lo han intentado y han fallado (y de manera bastante espectacular).

La especificación OpenAPI es posiblemente la mejor implementación en este momento para este propósito exacto. Debido a cómo genera documentación, API a partir de una descripción, y lo hace de una manera tan dinámica y diversa, la Especificación OpenAPI une ambos mundos, permitiendo, como lo llama The API Handyman, la rapidez de la API .

Publicar un comentario

0 Comentarios