La API generada¶

Por cada tabla y vista del schema, tai-api generate escribe un conjunto de endpoints con la misma forma en todos los proyectos. Es lo que permite que un frontend sepa consultar una API de tai-api sin haberla visto antes, y lo que hace posible el cliente TypeScript.

Las rutas¶

/{schema}/{tabla-con-guiones}

El nombre de la tabla se pasa a guiones (etiqueta_publicacion → /etiqueta-publicacion); el del schema, no. Para una tabla publicacion del schema public:

Método	Ruta	Qué hace	Devuelve en `data`	Permiso
`GET`	`/public/publicacion`	Lista, con filtros, paginación, orden y relaciones	`PublicacionRead[]`	`read`
`GET`	`/public/publicacion/{id}`	Un registro por su clave	`PublicacionRead`	`read`
`GET`	`/public/publicacion/count`	Cuántos cumplen los filtros	`int`	`read`
`GET`	`/public/publicacion/exists`	Si hay alguno	`bool`	`read`
`GET`	`/public/publicacion/{campo}/sum` · `mean` · `max` · `min`	Una agregación sobre un campo	`AggRow[]`	`read`
`POST`	`/public/publicacion/agg`	Varias agregaciones y agrupación	`AggRow[]`	`read`
`POST`	`/public/publicacion`	Crea, con sus relaciones anidadas	`PublicacionRead` (201)	`create`
`POST`	`/public/publicacion/bulk`	Crea varios (hasta 1000), en una transacción	`PublicacionRead[]` (201)	`create`
`PATCH`	`/public/publicacion/{id}`	Actualiza un registro	filas afectadas	`update`
`PATCH`	`/public/publicacion`	Actualiza los que cumplen un filtro	filas afectadas	`update`
`DELETE`	`/public/publicacion/{id}`	Borra un registro	filas afectadas	`delete`
`DELETE`	`/public/publicacion`	Borra los que cumplen los filtros	filas afectadas	`delete`

Y una por schema, si tiene tablas: POST /public/_tx, varias escrituras de varias tablas en una sola transacción, con el permiso de cada una (Escritura).

Una vista solo tiene lecturas y agregaciones: no hay clave primaria que buscar ni filas que escribir.
Una clave primaria compuesta va en un segmento por columna, en el orden del schema: /public/etiqueta-publicacion/{publicacion_id}/{etiqueta}.
Los enumerados tienen su ruta: GET /public/enums/estado devuelve sus valores.
El operationId de cada operación es estable: {schema}_{tabla}_{operación} (public_publicacion_find_many).

La respuesta¶

Todo endpoint devuelve el mismo envoltorio, APIResponse:

{
  "status": "success",
  "data": [ … ],
  "message": "…",
  "errors": null,
  "meta": { "pagination": { "total": 120, "limit": 20, "offset": 0, "has_next": true, "has_prev": false } }
}

meta.pagination solo aparece en los listados cuando se pide limit u offset. Un error llega con status: "error" y el detalle en errors: ver Errores.

La marca del contrato¶

Toda respuesta lleva una cabecera con la marca de lo que expone la API, por schema:

X-Tai-Contract: public=3f9a1c2b7d40,ventas=91be04d2aa31,auth=8d1e0b2c4f6a

Son doce caracteres que cambian cuando cambia lo que expone la API —una columna, un filtro, una tabla— y solo entonces. Con autenticación lleva además auth=, la de /auth y /rbac, que depende de la forma de la sesión y de las reglas de RLS, no de si el backend es Database o Keycloak. El cliente TypeScript conoce la suya y avisa si no coinciden: se generó contra otra versión de la API.

La autorización apagada¶

Con autenticación y la autorización apagada —tai-api dev, sin --auth—, toda respuesta lleva además:

X-Tai-Auth: off

Esa respuesta no ha comprobado permisos ni RLS. Con la autorización encendida (tai-api dev --auth, producción) la cabecera no está. Se decide en cada petición, y el CORS la expone. El cliente TypeScript la lee para avisar: ver Contra tai-api dev.

Lo que no se genera¶

upsert y la búsqueda vectorial existen en el cliente Python de tai-sql, pero no se exponen por HTTP. create_many sí, como POST /{tabla}/bulk.
Los endpoints propios van en routers/custom/: ver Extender la API.

Página	Qué cuenta
Lectura	Filtros, paginación, orden y relaciones
Escritura	Altas con relaciones anidadas y sus permisos, actualizaciones, borrados masivos y transacciones de varias tablas (`_tx`)
Agregaciones	`sum`, `mean`, `max`, `min` y `agg`
Errores	Cómo llega un error, y qué código tiene cada uno
Documentación y salud	`/docs`, el OpenAPI, los diagramas, `/health` y MCP