Header Ads Widget

Ticker

6/recent/ticker-posts

Su guía para OpenAPI

 

Las API son el elemento vital de las aplicaciones y las empresas basadas en datos. Y, sin embargo, no hay dos servicios iguales. Esto ha creado grandes quebraderos de cabeza en términos de conseguir que las API se comuniquen entre sí. Eso sin mencionar los problemas que plantea sobre calidad, estándares y seguridad. Aquí es donde entra OpenAPI . OpenAPI, la especificación API estándar de la industria, se ha convertido en un aspecto esencial del éxito final de una API.

La conectividad y la colaboración son componentes clave para dirigir una organización exitosa, incluso si no está tratando de obtener ganancias. Quieres que las personas puedan encontrar tu empresa o marca. Si usted es un productor de API, desea que las personas también puedan encontrar sus datos e interactuar con ellos.

OpenAPI es una de las formas más eficientes de garantizar que sus datos sean accesibles para tantos consumidores de API como sea posible. OpenAPI también está firmemente en consonancia con el espíritu democrático e igualitario original de Internet, con su visión utópica de datos e información de alta calidad para todos. A continuación, analizamos en profundidad OpenAPI, una buena introducción para los recién llegados y una revisión para los desarrolladores de API experimentados por igual.

 


¿Qué es OpenAPI?

Especificación de OpenAPI

La especificación OpenAPI le permite describir una API REST utilizando un formato estandarizado. Le permite definir todos los puntos finales disponibles y las operaciones que están disponibles para un servicio. También le permite describir los métodos de autenticación de su API y la información de contacto, la licencia y los términos de uso pertinentes.

Las especificaciones de OpenAPI estandarizan las API, haciéndolas más universales e intercambiables. Esto es integral cuando consume varias API para una aplicación o producto, lo que se está volviendo cada vez más común. También crea la posibilidad de automatizar la generación de documentación , la generación de SDK , la inclusión de su API en un directorio de API, entre otras ventajas.

OpenAPI se llamó originalmente Swagger , parte de una serie de herramientas de código abierto creadas por Smartbear. Fue desarrollado con el objetivo de permitir que una API describa su propio formato y contenido. Puede escribir especificaciones de OpenAPI utilizando JSON o YAML . Ambos son fácilmente legibles por máquinas y humanos por igual.

 

¿Qué es la iniciativa OpenAPI?

No se confunda: existe la especificación OpenAPI, que detalla cómo describir las API, y existe la definición de OpenAPI en sí. Luego está la Iniciativa OpenAPI , un grupo de desarrolladores con visión de futuro que intentan promover la agenda de OpenAPI.

Como parte de la Fundación Linux, la iniciativa OpenAPI impulsa la estandarización de OpenAPI y el software de código abierto relacionado. Su objetivo es implementar la estandarización de API, así como proporcionar herramientas sólidas para usar el estándar. Legitima el proyecto OpenAPI al garantizar que los desarrolladores de alto nivel estén trabajando en el proyecto. Esto ha hecho posible que las principales empresas, como Capital One, PayPal e incluso Google, adopten la especificación OpenAPI.

 

Cómo funciona OpenAPI

OpenAPI describe una API mediante un documento o una serie de documentos, que detalla su estructura y contenido. Los documentos de OpenAPI pueden estar en formato JSON o YAML. El archivo OAS es similar a un archivo de esquema API .

Los archivos OAS se pueden crear desde cero. O puede utilizar herramientas que le ayuden en el camino. Por ejemplo, Smartbear proporciona muchas herramientas para comenzar:

  • Utilice Swagger Editor para definir las variables de OpenAPI.
  • Utilice Swagger Codegen para agregar la implementación del servidor fácilmente.
  • Utilice la versión en línea, SwaggerHub , para colaborar en el diseño, desarrollo y creación de API como equipo.
  • Finalmente, use la interfaz de usuario de Swagger para visualizar y documentar sus archivos OAS. La documentación es fundamental para mostrar a los consumidores cómo interactuar con los recursos.

Los archivos OpenAPI también se pueden generar rápidamente para las API existentes. También hay varias herramientas Swagger para esto. Swagger Core genera archivos OAS para las API existentes utilizando los marcos JAX-RS o node.js. Swagger Inspector le permite generar una definición OAS para cualquier punto final de API directamente desde su navegador.

Suponga que es un consumidor de API que desea interactuar con una API que tiene un archivo de especificación de OpenAPI. En ese caso, también puede utilizar Swagger Inspector o Swagger UI para explorar la API, siempre que tenga la URL de las definiciones de Swagger de la API. A continuación, puede generar una biblioteca cliente.

Sin embargo, esto es solo la punta del iceberg cuando se trata de herramientas OpenAPI. Considere el Portal de experiencia para desarrolladores de Apimatic , por ejemplo. Le brinda todo, desde un explorador de API hasta un generador de documentación y generación de código. El Portal de experiencia para desarrolladores cuesta un poco, pero es relativamente económico y vale la pena mencionarlo debido a sus amplias capacidades.

También hay muchas herramientas y recursos OpenAPI gratuitos y de código abierto , por supuesto. Considere el conjunto de servicios que ofrece Apicurio , que son herramientas basadas en la web que le permiten hacer de todo, desde diseñar sus propias API hasta generar esquemas y documentación.

OpenAPI abre la puerta a los no desarrolladores y a las personas con menos conocimientos técnicos para usar y consumir API. Esto probablemente marcará el comienzo de una nueva era de aplicaciones, herramientas, productos y recursos basados ​​en datos.

Beneficios de OpenAPI

En 2019, escribiendo para Newstack, el autor John Feeney analiza la necesidad de adoptar las API para las empresas basadas en datos que desean seguir siendo exitosas. “Convertirse en un productor de API puede ofrecer enormes dividendos en términos de crecimiento e ingresos. Para las empresas que realmente han adoptado una estrategia de API primero, han creado un nuevo canal de comercialización que genera ingresos sustanciales a partir de las tarifas de uso y referencias ".

Hay muchas historias de éxito de API. Stripe, Twilio , Salesforce, Shopify y otras se han convertido en empresas multimillonarias gracias a la adopción de una estrategia basada en API. También hemos visto un aumento en las nuevas empresas impulsadas por API que se apoderan de Silicon Valley . En otras empresas, las API han aportado beneficios indirectos para complementar el negocio existente.

En este punto, debería comenzar a ver los beneficios de usar OpenAPI. Las API ya no son una industria artesanal, una industria de nicho o una técnica para programadores y desarrolladores incondicionales. Las API son una industria por derecho propio. Eso significa que deben ser accesibles y comprensibles para una amplia muestra representativa de diferentes consumidores de API, todos con diferentes niveles de capacidades técnicas.

Tener estándares establecidos para crear y consumir API es beneficioso tanto para los desarrolladores de API como para los consumidores.

Diseño colaborativo de API

Las API están destinadas a ser utilizadas . Con eso en mente, a menudo es un error que una API sea diseñada e implementada por una sola persona. Para que una API sea lo más útil posible, el desarrollador debe tener en cuenta al consumidor final. Las especificaciones de OpenAPI garantizan de forma inherente que todos estén en la misma página.

El formato estandarizado también significa que varias personas pueden trabajar en la misma API. Los archivos OpenAPI se pueden almacenar en directorios compartidos como GitHub, donde se pueden agregar, bifurcar o clonar fácilmente. Este enfoque colaborativo es excelente para crear versiones y documentar el historial de una API. También es ideal para el diseño colaborativo de API, ya que la naturaleza estandarizada de OpenAPI permite generar código a partir del archivo de especificación.

OpenAPI también garantiza que la documentación se mantenga actualizada y esté conectada a los cambios que ocurren en la API. Estos se pueden hacer cumplir mediante procesos de integración continua .

Ahorra tiempo y evita errores

El uso de un formato estandarizado significa que algunos aspectos del desarrollo se pueden automatizar. La herramienta Codegen de Swagger puede crear código en torno a la especificación OpenAPI. Codegen se puede utilizar para generar código automáticamente para implementaciones de servidor, por ejemplo. Incluso puede crear un servidor simulado completo para que el cliente pueda probar la API antes de implementarla.

La estandarización hace posible que los desarrolladores externos creen herramientas similares. Por ejemplo, recursos como APIMatic traducen una especificación de OpenAPI en un SDK para cualquier entorno de desarrollo que utilice.

Asegura la calidad

Tener un formato uniforme ayuda a estandarizar su proceso de desarrollo de API de principio a fin. También ayuda a que sea posible probar su API durante el proceso de desarrollo. Puede transferir definiciones de OpenAPI a aplicaciones como Postman para probar la API manualmente .

Tener esa especificación en su lugar también significa que también puede probar otras API. Esto significa que puede probar cualquier API adicional que pueda estar utilizando, lo que ayuda a garantizar que cualquier producto que cree utilizando varias API sea lo más estable posible.

Genere documentación interactiva y atractiva

Incluso si las API van a terminar siendo legibles por máquina, en última instancia, aún deben ser comprensibles para el usuario. OpenAPI también hace posible estandarizar y automatizar la creación de documentación.

La documentación estandarizada también facilita a los desarrolladores y consumidores de API probar una API. Usando una caja de arena, pueden enviar fácilmente una solicitud desde su navegador para audicionar una API sin tener que escribir ningún código propio.

Existe una amplia gama de herramientas de generación de documentación de API disponibles utilizando la especificación OpenAPI, muchas de las cuales son de código abierto. LucyBot le permite generar documentación API como una página web. ReDoc es un generador de API de código abierto que está disponible en GitHub.

La documentación estandarizada también ayuda a brindar a los desarrolladores de API una lista de verificación para consultar cuando crean sus API. Hace que sea mucho menos probable que no se pasen por alto los elementos esenciales de la API.

Hace que su API sea comercializable y visible

Si desea que su API tenga éxito , las personas deben poder usarla . Esto incluye a los no programadores y laicos, especialmente si está desarrollando una API como producto.

Seguir las especificaciones de OpenAPI significa que los consumidores de API pueden usar sus herramientas y recursos preferidos para explorar su API. También facilita la integración de varias API en una aplicación.

La inclusión de un archivo OpenAPI también hace que su API sea más legible por máquina. Esto facilita el envío de su API a los directorios y mercados de API , exponiendo su servicio a más desarrolladores a medida que comparan. También facilita el envío de su API a servicios como Microsoft Flow , haciéndolos consumibles para aquellos que buscan implementar una plataforma integrada como servicio (IPaaS).

Ejemplo de OpenAPI

Completaremos nuestra introducción a OpenAPI con un ejemplo del mundo real para ayudarlo a visualizar el formato y cómo puede integrarlo en su flujo de trabajo de desarrollo de API.

Así es como se ve una especificación de OpenAPI 3.0 como un archivo YAML:

openapi: 3.0.0
info:
  title: Pet Store
  description: API for Pet Store Online Portal.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Main API server
  - url: http://staging-api.example.com
    description: Sandboxing server
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Retrieves all of Pet Store's users.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

Analizaremos esto un poco para que pueda hacerse una idea de lo que está sucediendo.

La primera línea contiene los metadatos de OpenAPI, que detallan qué versión se utilizó para la creación.

La sección de información contiene toda la información básica de la API - title, descriptiony version. versiones la versión actual de tu API, no la versión de OpenAPI, por cierto, así que asegúrate de no confundir las dos.

La sección del servidor es donde incluye los detalles de su servidor API. También puede incluir varios servidores, por lo que puede incluir información separada para los entornos de producción y sandbox. La sección del servidor también dictará automáticamente el resto de la dirección de su API. Entonces, si la dirección de su servidor fuera , el punto final sería .https://apiexample.example.com/v1/userhttps://apiexample.example.com/v1/USER

La sección de rutas presenta puntos finales individuales. También define qué operación se puede utilizar en ese punto final. Las operaciones se pueden desglosar aún más mediante el uso de rutas de URL, consultas, encabezados y cookies.

Si una operación envía una solicitud, OpenAPI también puede describir el cuerpo mediante la requestBodypalabra clave, que describe el cuerpo de la solicitud, así como los tipos de medios que admite.

La sección de respuesta de la especificación de OpenAPI detalla todas las diferentes respuestas que su API puede entregar, como los códigos de estado HTTP. Esta es una nueva adición a OpenAPI 3.0 , dicho sea de paso, ya que no era necesaria en las versiones anteriores.

La sección de componentes / esquema le permite dictar las estructuras de datos comunes que se utilizan en su API. Se puede hacer referencia a estos mediante $ ref siempre que se requiera un esquema.

Finalmente, las securitySchemessecciones de seguridad y le permiten describir qué tipo de autenticación se utiliza en su API.

Puede leer las especificaciones completas de OpenAPI 3.0 en GitHub .

OpenAPI: pensamientos finales

Estandarizar las API es una necesidad ineludible. A medida que las API pasan de ser un nicho de interés para los analistas de datos apasionados a ser el alma de la economía impulsada por los datos , será necesario garantizar que las API sean consumibles y detectables , sin mencionar intercambiables y seguras.

OpenAPI está sentando las bases para un marco API estandarizado, similar a las partes estandarizadas. Al igual que las piezas estandarizadas, OpenAPI podría abrir las compuertas en la próxima Revolución Industrial, al mismo tiempo que facilitaría la vida tanto a los desarrolladores como a los consumidores de API.

Publicar un comentario

0 Comentarios