La API de Cloudflare utiliza ahora esquemas OpenAPI

Hoy anunciamos la disponibilidad general de Esquemas de OpenAPI para Cloudflare API. Estos se publican a través de GitHub y se actualizarán regularmente a medida que Cloudflare agregue y actualice las API. OpenAPI es el estándar ampliamente adoptado para definir API en un formato legible por máquina. Los esquemas OpenAPI permiten la capacidad de conectar nuestra API a una amplia gama de herramientas para acelerar el desarrollo para nosotros y nuestros clientes. Internamente, nos facilitará el mantenimiento y la actualización de nuestras API. Antes de hablar de esos beneficios, comencemos con lo básico.

Gran parte de Internet está basado en API (interfaces de programación de aplicaciones) o las proporciona como servicios a clientes de todo el mundo. Esto permite que los ordenadores se comuniquen entre sí de manera estandarizada. OpenAPI es un estándar ampliamente adoptado sobre cómo definir las API. Esto permite que otras máquinas analicen esas definiciones de manera confiable y las usen de maneras interesantes. El producto API Shield de Cloudflare utiliza esquemas OpenAPI para proporcionar validación de esquemas para garantizar que solo se envíen a su origen solicitudes API bien formadas.

Cloudflare tiene una API que los clientes pueden usar para interactuar con nuestros productos de seguridad y rendimiento desde otros lugares en Internet. ¿Cómo definimos nuestras propias API? En el pasado, usábamos un estándar llamado JSON Hyper-Schema. Eso nos había funcionado bien, pero a medida que pasaba el tiempo queríamos adoptar más herramientas que pudieran beneficiarnos a nivel interno y facilitar la vida de nuestros clientes. La comunidad de OpenAPI ha florecido en los últimos años proporcionando muchas capacidades, como discutiremos, que no estaban disponibles mientras usábamos JSON Hyper-Schema. A partir de hoy, usamos OpenAPI.

Puede obtener más información sobre OpenAPI aquí. Tener un estándar abierto y bien entendido para definir nuestras API permite que se utilicen herramientas e infraestructura compartidas que pueden leer estas definiciones estándar. Veamos algunos ejemplos.

La mayoría de los clientes no necesitarán usar los esquemas para ver el valor. El primer sistema que aprovecha los esquemas OpenAPI es nuestro nuevo API Docs que se anunciaron hoy. Debido a que ahora tenemos esquemas OpenAPI, aprovechamos la herramienta de código abierto Stoplight Elements para ayudar a generar este nuevo sitio de documentos. Esto nos permitió retirar nuestro sitio previamente personalizado que era difícil de mantener. Además, muchos ingenieros de Cloudflare están familiarizados con OpenAPI, por lo que los equipos pueden escribir nuevos esquemas más rápido y es menos probable que cometan errores al usar un estándar que los entienden al definir nuevas API.

Sin embargo, hay formas de aprovechar los esquemas directamente. La comunidad OpenAPI tiene un gran número de herramientas que solo requieren un conjunto de esquemas para poder usar. Dos de estos ejemplos son las API simuladas y la generación de bibliotecas.

Supongamos que tiene un código que llama a la API de Cloudflare y desea poder ejecutar fácilmente pruebas de unidad localmente o pruebas de integración en su canal de CI/CD. Aunque podría simplemente llamar a la API de Cloudflare en cada ejecución, es posible que no desee hacerlo por algunos motivos. Primero, es posible que desee ejecutar pruebas con la frecuencia suficiente para que gestionar la creación y eliminación de recursos se vuelva una molestia. Además, en muchas de estas pruebas, no necesariamente está intentando validar la lógica en Cloudflare, sino el comportamiento de su propio sistema. En este caso, simulando la API de Cloudflare sería ideal, ya que puede estar seguro de que no está violando el contrato de la API de Cloudflare, pero sin tener que preocuparse por los detalles de la gestión de recursos reales. Además, la simulación le permite simular diferentes escenarios, como tener una tasa limitada o recibir 500 errores. Esto le permite probar su código en circunstancias normalmente raras que pueden terminar teniendo un impacto serio.

Por ejemplo, Stoplight Prism podría usarse para simular la API de Cloudflare con el fin de hacer pruebas. Con una copia local de los esquemas API de Cloudflare, puede ejecutar el siguiente comando para activar un servidor simulado local:

Luego, puede enviar solicitudes al servidor simulado para validar que su uso de la API de Cloudflare no infringe el contrato de la API localmente:

$ docker run --init --rm \
  -v /home/user/git/api-schemas/openapi.yaml:/tmp/openapi.yaml \
  -p 4010:4010 stoplight/prism:4 \
  mock -h 0.0.0.0 /tmp/openapi.yaml

Esto significa un desarrollo más rápido y ejecuciones de pruebas más cortas, al mismo tiempo que detecta los problemas de contrato de API antes de que se fusionen o implementen.

$ curl -sX PUT localhost:4010/zones/f00/activation_check \
  -Hx-auth-email:[email protected] -Hx-auth-key:foobarbaz | jq
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353"
  }
}

Cloudflare tiene bibliotecas en muchos lenguajes de programación como Terraform y Go, pero no ofrecemos soporte para todos los lenguajes de programación posibles. Afortunadamente, al usar una herramienta como el generador openapi, puede alimentar los esquemas de la API de Cloudflare y generar una biblioteca en una amplia gama de idiomas para luego usarla en su código para comunicarse con la API de Cloudflare. Por ejemplo, podría generar una biblioteca Java al usar los siguientes comandos:

Luego, comience a usar ese cliente en su código Java para hablar con la API de Cloudflare.

git clone https://github.com/openapitools/openapi-generator
cd openapi-generator
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
   -i https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.yaml \
   -g java \
   -o /var/tmp/java_api_client

Como se mencionó antes, anteriormente usábamos JSON Hyper-Schema para definir nuestras API. Tenemos aproximadamente 600 puntos de conexión que ya estaban definidos en los esquemas. Aquí hay un snippet de cómo se ve un punto de conexión en JSON Hyper-Schema:

Veamos el mismo punto de conexión en OpenAPI:

{
      "title": "List Zones",
      "description": "List, search, sort, and filter your zones.",
      "rel": "collection",
      "href": "zones",
      "method": "GET",
      "schema": {
        "$ref": "definitions/zone.json#/definitions/collection_query"
      },
      "targetSchema": {
        "$ref": "#/definitions/response_collection"
      },
      "cfOwnership": "www",
      "cfPlanAvailability": {
        "free": true,
        "pro": true,
        "business": true,
        "enterprise": true
      },
      "cfPermissionsRequired": {
        "enum": [
          "#zone:read"
        ]
      }
    }

Puede ver que los dos se ven bastante parecidos y, en su mayor parte, la misma información está contenida en cada uno, incluido el tipo de método, una descripción y las definiciones de solicitud y respuesta (aunque están vinculadas en $refs). El valor de migrar de uno a otro no es el cambio en cómo definimos los esquemas en sí, sino en lo que podemos hacer con estos esquemas. Una gran cantidad de herramientas pueden analizar la última, OpenAPI, mientras que muchas menos pueden analizar la primera, JSON Hyper-Schema.

/zones:
    get:
      description: List, search, sort, and filter your zones.
      operationId: zone-list-zones
      responses:
        4xx:
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/components-schemas-response_collection'
                - $ref: '#/components/schemas/api-response-common-failure'
          description: List Zones response failure
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/components-schemas-response_collection'
          description: List Zones response
      security:
      - api_email: []
        api_key: []
      summary: List Zones
      tags:
      - Zone
      x-cfPermissionsRequired:
        enum:
        - '#zone:read'
      x-cfPlanAvailability:
        business: true
        enterprise: true
        free: true
        pro: true

Si esta API fuera todo lo que conformó la API de Cloudflare, sería fácil simplemente convertir el JSON Hyper-Schema en el Esquema de OpenAPI a mano y terminarlo. Sin embargo, hacer esto 600 veces iba a ser una enorme tarea. Al considerar que los equipos agregan constantemente nuevos puntos de conexión, sería imposible mantenerse al día. También se dio el caso de que nuestros documentos de API existentes usaban el JSON Hyper-Schema existente, por lo que eso significaba que debíamos mantener ambos esquemas actualizados durante cualquier período de transición. Tenía que haber una mejor manera.

Dado que tanto JSON Hyper-Schema como OpenAPI son estándar, se puede deducir que debería ser posible tomar un archivo en un formato y convertirlo a otro, ¿verdad? Por suerte, ¡la respuesta es sí! Creamos una herramienta que tomó todos los JSON Hyper-Schema existentes y generó esquemas OpenAPI totalmente compatibles. Por supuesto, esto no sucedió de la noche a la mañana, pero debido a las herramientas OpenAPI existentes, pudimos mejorar de manera iterativa el convertidor automático y ejecutar las herramientas de validación de OpenAPI sobre los esquemas de salida para ver qué problemas tenía aún la herramienta de conversión.

Después de muchas iteraciones y mejoras en la herramienta de conversión, finalmente logramos esquemas OpenAPI Spec totalmente compatibles que se generaron automáticamente a partir de nuestro JSON Hyper-Schema existente. Mientras creábamos esta herramienta, los equipos seguían agregando y actualizando los esquemas existentes y nuestro equipo de Contenido del producto también actualizaba el texto en los esquemas para que nuestros documentos API fueran más fáciles de usar. ¡El beneficio de este proceso es que no tuvimos que ralentizar nada de ese trabajo, ya que todo lo que cambió en los esquemas antiguos se reflejó automáticamente en los nuevos esquemas!

Una vez que la herramienta estuvo lista, el siguiente paso fue decidir cuándo y cómo dejaríamos de realizar actualizaciones a JSON Hyper-Schemas y trasladaríamos todos los equipos a esquemas OpenAPI. Los (ahora antiguos) documentos de API eran la mayor preocupación, dado que solo entendían JSON Hyper-Schema. ¡Gracias a la ayuda de nuestros equipos de Experiencia del desarrollador y contenido de producto, pudimos lanzar los nuevos documentos de API hoy y podemos cambiar oficialmente a OpenAPI hoy también!

Ahora que nos hemos pasado por completo a OpenAPI, hay más oportunidades disponibles. Internamente, investigaremos qué herramientas podemos adoptar para ayudar a reducir el esfuerzo de los equipos individuales y acelerar el desarrollo de API. Una idea que estamos explorando es la creación automática de esquemas openAPI a partir de notaciones de código. A nivel externo, ahora tenemos las herramientas fundamentales necesarias para comenzar a explorar cómo generar automáticamente y admitir más bibliotecas de lenguaje de programación para que las utilicen los clientes. También nos entusiasma ver lo que usted puede hacer con los esquemas, así que si hace algo interesante o tiene ideas, ¡no dude en compartirlas con nosotros!