# Cómo se generan los SDK

> Los SDK se generan desde el contrato OpenAPI de la API y los sirve la propia API, así que el fichero que descargas siempre coincide con ella.

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](https://developers.openwaf.dev/es/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.

```sh
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 descargarlo
```

Revisa 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](https://developers.openwaf.dev/es/api/).