Post Top Ad

Your Ad Spot

jueves, 20 de agosto de 2020

Cómo escribir su primera especificación AsyncAPI

La especificación AsyncAPI es un lenguaje de especificación completo para describir las API de mensajería asincrónica. Como un cohete con destino a la Estación Espacial Internacional, su popularidad se ha disparado en los últimos años, y continúa haciéndolo, con la creciente adopción de protocolos de IoT y arquitecturas API impulsadas por eventos. Entonces, ¿qué pasa si desea participar en parte de la acción, documentando su API de mensajería con AsyncAPI?
En esta guía para principiantes de la especificación AsyncAPI, lo guiaremos a través del proceso de creación de su archivo de especificación, paso a paso. Nos centraremos en los cinco objetos cada necesidades espec - la asyncapiversión, infoserverschannels, y components- proporcionar algunos fragmentos de código ligeramente espacio de temática a lo largo del camino.

Herramientas: AsyncAPI Playground

Lo primero es lo primero: herramientas. Al igual que la especificación OpenAPI en la que se basó, puede crear archivos de especificación AsyncAPI en JSON o YAML. Esto significa que puede escribir la especificación para su API usando cualquier editor de texto de su elección.
Dicho esto, hay un editor dedicado para las especificaciones de AsyncAPI llamado AsyncAPI Playground . No solo muestra su archivo de especificación de una manera elegante y legible, sino que también valida y representa la especificación a medida que trabaja en ella. Para su primera especificación AsyncAPI, definitivamente le recomendamos que la use.

Escribir su especificación AsyncAPI: de principio a fin

Entonces, ha abierto Playground y está listo para comenzar a describir su API. Como se prometió, le mostraremos cómo escribir la especificación objeto por objeto, de principio a fin.
Todos los objetos marcados con un asterisco (*) son obligatorios.

Versión de AsyncAPI *

Un elemento imprescindible para cualquier especificación AsyncAPI es la versión AsyncAPI, que se indica con la asyncapiclave. En este caso, buscaremos la versión más reciente de la especificación:
asyncapi: 2.0.0

Info *

El siguiente es el infoobjeto, que alberga metadatos de API. Específicamente, se compone de seis campos - titleversiondescriptiontermsOfServicecontact, y license- de los cuales sólo titleversionse requieren (ambas cadenas).
Si opta por completar los otros campos, tenga en cuenta que descriptiontermsOfServicetambién son cadenas, mientras que contactlicenseutilice los respectivos formatos de Objeto de contacto y Objeto de licencia definidos por la especificación.
Optemos por el término medio e incluyamos algunos campos opcionales en nuestro infoobjeto:
info:
  title: Rocket API
  version: '1.0.0'
  contact:
    name: Space Agency
    url: https://spaceagency.example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

Servidores

También es importante el serversobjeto, que define dónde y cómo el cliente puede comunicarse con varios intermediarios de mensajes u otros servidores. Este objeto es un mapa de serverobjetos (observe que ahora es un servidor singular ), que a su vez deben contener un urlprotocol, y pueden incluir otros campos como securityinformación en forma de un objeto de requisito de seguridad .
servers:
  production:
    url: api.spaceagency.example.com
    protocol: mqtt

Canales *

Con channels, que son similares a los pathsutilizados en OpenAPI, podemos empezar a entrar en la funcionalidad real de la API. Cada channelobjeto debe su nombre a la URI adecuada, y puede contener los seis campos siguientes: $refdescriptionsubscribepublishparametersbindings.
Los objetos subscribepublishdescriben si y cómo, lo adivinó, el cliente puede suscribirse o publicar en ese canal, en forma de un objeto de operación . También se destacan parametersbindings, que describen (respectivamente) los parámetros incluidos en el nombre del canal y las propiedades de canal específicas del protocolo.
Así es como channelspodría verse el objeto:
channels:
  rocket/{rocketId}/status:
    parameters:
      rocketId:
        $ref: '#/components/parameters/rocketId'
    subscribe:
      summary: Receive status updates for a rocket.
      message:
        $ref: '#/components/messages/rocketStatus'

Componentes

En esa última muestra de código, es posible que haya notado dos referencias a componentsobjetos. En cierto modo, estos son el pan y la mantequilla de la Especificación AsyncAPI, que proporciona objetos detallados y reutilizables para una larga lista de tipos de objetos:
  • schemas
  • messages
  • securitySchemes
  • parameters
  • correlationIds
  • operationTraits
  • messageTraits
  • serverBindings
  • channelBindings
  • operationBindings
  • messageBindings
Son todos estos los componentsque permiten que la especificación describa con precisión el comportamiento de una API. Para simplificar las cosas, veamos las dos referencias de componentes que usamos dentro del channelsobjeto:
components:
  messages:
    rocketStatus:
      payload:
        type: object
        properties:
          ...
  parameters:
    rocketId:
      description: The ID of the rocket.
      schema:
        type: string

Uniendo las piezas

Si juntamos todas las piezas, terminamos con una especificación AsyncAPI muy rudimentaria que define un solo canal al que el cliente puede suscribirse, los parámetros que necesita proporcionar para hacerlo y qué cargas útiles pueden esperar recuperar:
asyncapi: 2.0.0
info:
  title: Rocket API
  version: '1.0.0'
  contact:
    name: Space Agency
    url: https://spaceagency.example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  production:
    url: api.spaceagency.example.com
    protocol: mqtt
channels:
  rocket/{rocketId}/status:
    parameters:
      rocketId:
        $ref: '#/components/parameters/rocketId'
    subscribe:
      summary: Receive status updates for a rocket.
      message:
        $ref: '#/components/messages/rocketStatus'
        
components:
  messages:
    rocketStatus:
      payload:
        type: object
        properties:
          ...
  parameters:
    rocketId:
      description: The ID of the rocket.
      schema:
        type: string
Y así es como se ve cuando se renderiza en Playground:

Obviamente, la especificación AsyncAPI le permite describir su API con mucho más detalle. Para hacerlo, querrá consultar la documentación , que explica los muchos objetos AsyncAPI en todo su esplendor, y GitHub , donde puede ver más ejemplos de la especificación en acción.

Pensamientos finales

Ya sea que desee rastrear el estado de los cohetes o algo más mundano, la Especificación AsyncAPI es el estándar de elección para definir API asincrónicas. Esta breve guía ha analizado los cinco objetos básicos que debe incluir en su primera especificación AsyncAPI, pero hay mucho más. Afortunadamente, la especificación es familiar, intuitiva y bien documentada.

No hay comentarios.:

Publicar un comentario

Dejanos tu comentario para seguir mejorando!

outbrain

Páginas