Header Ads Widget

Ticker

6/recent/ticker-posts

Novedades de OpenAPI 3.0


 Si ha estado escondido debajo de una roca durante los últimos 18 meses, es posible que no sepa que la especificación de la API Swagger , posiblemente el formato de especificación más popular disponible para la comunidad de API, ha sido donada a la Fundación Linux para convertirse en la base de OpenAPI. Especificación . La Especificación OpenAPI (OAS) es compatible con varios pesos pesados ​​de la industria, incluidos Google, Microsoft e IBM, y su objetivo es:

"... para definir una interfaz estándar, independiente del idioma para las API REST, que permite que tanto los humanos como las computadoras descubran y comprendan las capacidades del servicio sin acceso al código fuente, la documentación o mediante la inspección del tráfico de la red"

Después de preparar un extenso trabajo atrasado, el Comité de Diseño Técnico (TDC) apoyado por la comunidad ha publicado un borrador de implementación de la especificación en la versión 3.0 . El borrador va acompañado de un tutorial para ayudar a los desarrolladores a conocer los cambios y a ponerse manos a la obra.

En esta publicación, analizaremos este tutorial y los cambios que introduce OAS 3.0, profundizaremos en los aspectos más destacados y trataremos de evaluar las implicaciones de las nuevas funciones tanto para los proveedores de API como para los consumidores.

Estandarización de la reutilización con el objeto Componentes

El borrador de la especificación incluye varios cambios estructurales y quizás el más importante es cómo los objetos de nivel raíz, como las definiciones, se han modificado para ser encapsulados por un objeto Componentes . El propósito del objeto Componentes es abordar las inconsistencias en el comportamiento de las propiedades de nivel raíz en la versión 2.0 y extender las oportunidades de reutilización a través de una especificación de API, es decir, cualquier cosa definida dentro del objeto Componentes está disponible para su reutilización en otro lugar pero ya no constituye un nivel raíz. objeto que es efectivamente de alcance global.

La implicación de encapsular objetos a nivel raíz y eliminar el alcance global es que las herramientas de generación de código de soporte solo deben crear definiciones de objetos cuando encuentran una referencia explícita; si no se hace referencia a un objeto, debe ignorarse. Si esta implicación es válida, esto le dará a los proveedores de API la capacidad de incluir definiciones de objetos de Componentes estándar con la expectativa de que los consumidores simplemente las ignoren si no se utilizan; Los consumidores de API también podrán generar código con una huella menor, ya que los objetos no utilizados serán igualmente ignorados (con obvias eficiencias en la revisión del código, prácticas de codificación seguras y mantenimiento).

Este enfoque obviamente vendría a costa de documentos de especificación sucintos y concisos, por lo que una posible mejora futura es permitir que un objeto de Componentes sea externalizado. Por supuesto, queda por ver si esta interpretación es válida ya que los desarrolladores decidirán cómo crear sus herramientas de generación de código.

Para los diseñadores y desarrolladores de API, el objeto Componentes ofrece ventajas significativas en la definición de objetos reutilizables ; por ejemplo, la reutilización de un objeto de parámetro es una verdadera bendición para aquellos que desean definir un solo parámetro y reutilizarlo en múltiples recursos o métodos, algo imposible en la versión 2.0 y alcanzable en lenguajes de descripción de API como RAML . A modo de ejemplo, un objeto de parámetro reutilizable se puede definir de la siguiente manera:

components:
parameters: NordicId: name: nordicId description: My Nordic APIs Identifier required: true type: string

A continuación, se puede hacer referencia a esto en otra parte de la especificación:

get:
parameters: - $ref: #/components/parameters/NordicId - name: another_random type: string description: Another random parameter as an example

Definición de varios servidores

Otro aspecto estructural destacado es la capacidad de definir varios servidores . Esto es importante ya que una API puede tener un alias varias veces, lo que brinda la opción de cómo se aloja una API. Los hosts también se pueden anular en el nivel de un objeto Path, lo que significa que se pueden alojar diferentes recursos en diferentes servidores.

Anular los hosts a nivel de ruta ofrece un soporte significativo para una arquitectura de microservicios , lo que brinda a los proveedores de API la capacidad de implementar varios microservicios descritos por una sola especificación de API ; por lo tanto, el proveedor puede ofrecer facilidad de uso para la comunidad de desarrolladores sin sacrificar su enfoque arquitectónico. Sin embargo, es posible que el uso de esta opción deba moderarse con precaución para las API que se consumen en el navegador, ya que el intercambio entre hosts cuando se realizan llamadas Ajax es probable que inflija algo de dolor en la forma de CORSAgregar varios servidores no crea un problema de CORS, ya existe cuando se realiza una llamada Ajax a un host diferente, pero podría exacerbarlo ya que los comportamientos deberán ser consistentes en todos los hosts que expone un proveedor de API. Los proveedores de API deben comprender a su audiencia antes de tomar esta decisión de diseño y, si corresponde, implementar suficiente manejo de CORS en el servidor para permitir que los navegadores realicen solicitudes entre sitios de forma segura.

¿Nuevo en OpenAPI Spec? Lea nuestro artículo sobre lo que significa la iniciativa OpenAPI para el espacio API

Mejoras para objetos de ejemplo

El cambio estructural final resaltado por el tutorial es la mayor flexibilidad de los objetos de ejemplo , que ahora se pueden usar para describir cualquier tipo de ejemplo en lugar de uno codificado en JSON o YAML; otros formatos como XML o texto sin formato se pueden expresar en una cadena JSON. La descripción de un ejemplo XML se puede hacer de la siguiente manera:

examples:
  - 'Nordic'
  - 'API'

El ejemplo también se puede externalizar mediante el uso de un objeto $ ref y aprovechar los objetos de contenido como se explica a continuación. También vale la pena señalar que el objeto Examples se está refinando y es probable que cambie antes del lanzamiento final de la especificación.

Estandarización de los parámetros y el contenido de las solicitudes

El borrador de la OEA introduce una estandarización importante de cómo se definen las definiciones de las solicitudes. En primer lugar, los parámetros de solicitud se definen como un objeto en lugar de como un subconjunto del objeto Parameter. Esto es importante ya que agrega algunos beneficios de reutilización significativos que no son posibles en la versión 2.0.

El objeto Request Body también aprovecha el nuevo objeto Content que tiene como objetivo proporcionar una vista multifacética de un objeto en el sentido de que describe diferentes tipos de contenido dentro de un solo objeto:

content:
  application/json:
  	schema:
  	  $ref: #/components/schemas/NordicExample
  	examples:
  	  -
  	    - Example1: Nordic
  	  -
  	    - Example2:
  	        Subject: API
  application/xml:
  	schema:
  	  $ref: #/components/schemas/NordicExample
    examples:
      - 'Nordic'
- 'API'

Por lo tanto, el objeto Contenido mejora significativamente la capacidad de definir múltiples tipos de contenido en una sola definición de solicitud o respuesta.

Soporte para Webhooks

La mayoría de los proveedores y consumidores de API son muy conscientes del hecho de que las API están implementando cada vez más mecanismos para establecer una comunicación bidireccional, al estilo de los patrones de publicación / suscripción y tecnologías como WebSockets . OAS reconoce este hecho al introducir el objeto Callback que proporciona un medio para definir un webhook en una especificación de API. El objeto de devolución de llamada se puede definir por operación principal, lo que permite una gran flexibilidad en los datos que puede transportar una devolución de llamada determinada. Además, también se proporciona un objeto Callbacks que permite definir un mapa de callbacks.

Consulte nuestra publicación sobre REST Hooks para ver cómo están evolucionando los webhooks.

Un guiño a los hipermedia

La aspiración de las API impulsadas por hipermedia (desde la perspectiva de aquellos en la comunidad de desarrolladores que desean crearlas) también se reconoce a través de la introducción del objeto Links . Las API impulsadas por hipermedia no eran explícitamente un objetivo en la versión 3.0 y los enlaces en este contexto son definiciones estáticas creadas en tiempo de diseño y no generadas dinámicamente. Describir una API impulsada por hipermedia de una manera adecuada sigue siendo difícil de alcanzar en OAS, agravado por el hecho de que existen muchos métodos diferentes y obstinados para definir una API impulsada por hipermedia y elegir una que "encaje" en OEA es difícil en sí mismo. Ya hay problemas abiertos destinados a la próxima versión (por ejemplo, el problema 577 muy detallado). Por tanto, la intención del borrador de la especificación del objeto Enlace es:

"... permiten la generación de bibliotecas cliente y documentación más útil que pueden encapsular el proceso de pasar de un recurso a otro".

Este parece ser un enfoque pragmático para proporcionar algo que la comunidad está buscando sin revisar completamente la estructura de la especificación de OpenAPI.

Esquema JSON (y otros)

El tutorial también hace referencia a lo que se ha tomado de JSON Schema , lo más pertinente es la inclusión de anyOf y oneOf que no estaban disponibles en la versión 2.0; este tema se trata ampliamente en el número 741 y en el propio borrador . Si bien el borrador amplía significativamente la inclusión de JSON Schema y lo convierte en un subconjunto totalmente compatible al eliminar el tipo de "archivo", no hay ninguna opción para incluir definiciones de JSON Schema nativas; como en la versión 2.0, un esquema debe definirse con un objeto Schema . La capacidad de utilizar el esquema JSON nativo se hace referencia en el trabajo pendiente en el número 275.y, obviamente, sería útil para los desarrolladores que intentan reutilizar las definiciones existentes. Además, también haría que OpenAPI sea funcionalmente equivalente a RAML a este respecto.

El tema de los esquemas alternativos también se analiza y cubre en el número 764 . Los esquemas alternativos darían a los proveedores de API más opciones para definir sus objetos; El esquema XML es casi con certeza el ejemplo más obvio de una alternativa y sería particularmente útil para los proveedores que buscan migrar de SOAP a REST y reutilizar sus objetos de parámetro de solicitud / respuesta de su WSDL. Además, la capacidad de intercambiar algo como JSON-LD podría mejorar la capacidad de los proveedores para definir API impulsadas por hipermedia y expresarlas (hasta cierto punto) a través de una especificación OAS.

Pensamientos finales

Se ha realizado una gran cantidad de trabajo para producir este borrador y la comunidad en su conjunto debería estar agradecida al TDC y a aquellos que los apoyan por el progreso realizado en el avance de la especificación. La mejora en los objetos que ofrece la especificación es sumamente valiosa para simplificar los medios para crear definiciones que se pueden reutilizar en toda una especificación de API.

No hace falta decir, sin embargo, que actualmente existe una brecha entre el borrador y las herramientas que lo soportan (como Swagger Editor ). Será emocionante ver cómo continúa evolucionando cuando estas herramientas implementen la versión 3.0 y la especificación se ejercite en el mundo real.

Esta publicación es, por supuesto, solo un resumen y hay otros cambios, como la documentación externa y las definiciones de seguridad, que también son valiosas para los desarrolladores. También hay muchos problemas abiertos en la acumulación que deben tenerse en cuenta para versiones futuras sobre una amplia cantidad de temas. Si desea participar en la evolución de la próxima versión, consulte estos enlaces:

Publicar un comentario

0 Comentarios