Los dos SDK se generan desde el contrato OpenAPI 3.1 de la API de OpenWAF, el mismo que hay detrás de la referencia de la API. El generador es determinista: el mismo contrato produce siempre los mismos ficheros, y la compilación falla si los ficheros publicados se quedan atrás respecto al contrato.
De dónde salen los ficheros
La API sirve los ficheros con los que se compiló:
| Fichero | URL | Tipo de contenido |
|---|---|---|
| TypeScript | https://dash.openwaf.dev/v1/sdk/openwaf.ts | application/typescript |
| Python | https://dash.openwaf.dev/v1/sdk/openwaf.py | text/x-python |
Son públicos (sin token), llevan un ETag (If-None-Match responde 304 Not Modified) y se pueden guardar en caché cinco minutos. Como van dentro de la API, el fichero que descargas siempre coincide con la API en funcionamiento. Los SDK no se publican en npm ni en PyPI: el fichero se guarda en tu proyecto.
Actualizaciones
Cuando la API gana operaciones o campos, vuelve a descargar el fichero. El ETag son los 32 primeros caracteres hexadecimales del SHA-256 del fichero, así que un script puede saber si tu copia está al día sin descargarla: envíalo en If-None-Match y un 304 significa que no ha cambiado.
ETAG="\"$(shasum -a 256 openwaf.ts | cut -c1-32)\""
curl -sS -o /dev/null -w '%{http_code}\n' -H "If-None-Match: $ETAG" https://dash.openwaf.dev/v1/sdk/openwaf.ts
# 304: al día · 200: vuelve a descargarloRevisa las diferencias antes de guardarlo, como con cualquier dependencia.
Qué incluyen
Los SDK exponen todas las operaciones que puede llamar un token de API (owf_…): todo lo que cuelga de /v1/orgs/{org}, la llamada que indica la organización del token (GET /v1/orgs) y las CA públicas de TLS hacia el origen. Quedan fuera el inicio de sesión, el endpoint MCP, la administración de la plataforma, las rutas de los nodos de borde, las propias descargas de los SDK y los flujos de eventos en directo (Server-Sent Events, que se leen con un EventSource).
El rol y el alcance de tu token siguen aplicando: el método de una operación que tu token no puede llamar falla con 403.
Cómo corresponden los métodos a las operaciones
| TypeScript | Python | |
|---|---|---|
| Nombre del método | El id de la operación, como listZones, createRecord, getZoneDiff | En snake_case: list_zones, create_record, get_zone_diff |
| Parámetros de ruta y de consulta | Un objeto: { zone, limit, before } | Argumentos con nombre: zone=…, limit=… |
| Cuerpo de la petición | body en el mismo objeto | body= |
| Opciones de cambio | Segundo argumento: { reason, ifMatch, dryRun } | Argumentos con nombre: reason=, if_match=, dry_run= |
org | Opcional; por defecto, la organización del cliente | Igual |
| Respuesta | El cuerpo JSON decodificado, tipado | El cuerpo JSON decodificado (dict) |
Los parámetros cuyo nombre es una palabra reservada llevan un guion bajo en Python: el from de las diferencias es from_. El comentario de cada método repite el resumen de la operación del contrato (en español) y su método y ruta HTTP.
Los ids de las operaciones y sus parámetros son los de la referencia de la API.