Saltar a contenido

tai-api

Framework declarativo de Python, sobre FastAPI, que convierte un schema de tai-sql en una API REST completa. No se escriben endpoints: se declara la base de datos con tai-sql, se declara quién puede hacer qué en un fichero de permisos, y tai-api genera el resto —endpoints, autenticación, permisos, filtrado por fila, documentación— y el cliente TypeScript que la consume.

schemas/public.py (tai-sql) ──▶ tai-api generate ──▶ la API: /public/<tabla>, /auth, /rbac, /docs
rbac/main.py                ──▶ tai-api rbac push ──▶ permisos, roles y RLS en la base de datos o en Keycloak
                                tai-api generate ──▶ el cliente TypeScript del frontend

La API que genera tiene la misma forma en todos los proyectos: un frontend sabe consultarla sin haberla visto antes.

Empieza por aquí

  • Instalación

    Qué instalar, y por qué son dos instalaciones y no una.

    Instalación

  • Tu primera API

    De un schema de tai-sql a una API con login, paso a paso.

    Primera API

  • La API generada

    Las rutas de cada tabla, sus filtros y cómo llega un error.

    La API

  • El cliente TypeScript

    El cliente de React o Svelte, con la sesión ya resuelta.

    El cliente

Los principios que explican el resto

  1. La API es un derivado desechable. Sale del schema de tai-sql y del .taiapiproject, y se regenera entera. Lo generado no se edita: si no hace lo que necesitas, se cambia la declaración o se extiende por los puntos previstos.
  2. tai-api no reimplementa nada de tai-sql. Los modelos, los DTOs y los DAOs son el cliente que genera tai-sql; tai-api aporta lo que tai-sql no hace: la capa HTTP, la identidad, los permisos y el filtrado por fila.
  3. El código generado nunca importa tai_api. tai-api es una herramienta de desarrollo: la API se despliega donde no está instalado.
  4. La configuración se hornea. Lo que declara el proyecto acaba escrito en el código generado; lo que viene del entorno son solo los secretos y las URLs. Cambiar una política exige regenerar y volver a desplegar.
  5. Un error dice cómo arreglarlo. Todo error del CLI trae su solución, y la API responde con códigos estables que un cliente puede interpretar.

Un vistazo

GET  /public/publicacion?in_estado=publicada&includes=autor&limit=20
POST /public/publicacion          { "titulo": "Hola", "autor_id": 3 }
GET  /public/publicacion/count?autor_id=3
POST /auth/main/login             { "username": "ana", "password": "…" }

# rbac/main.py
from tai_api.rbac import source, role

source(realm_name="main", dbschemas=["public"])

role("lector", api_permissions=["publicacion-read", "autor-read"])
role("editor", api_permissions=["publicacion-create", "publicacion-update"], subroles=["lector"])

const api = createTaiClient()
await api.session.restore()

const { data } = await api.public.publicacion.findMany({ in_estado: ['publicada'], limit: 20 })

Cómo está organizado este manual

Sección Qué responde
Inicio Qué instalar, cómo montar un proyecto y cómo es por dentro
La API Qué endpoints tiene cada tabla, cómo se consultan y cómo llegan los errores
Autenticación Los dos modos, la sesión, los permisos y el filtrado por fila
El cliente TypeScript El cliente del frontend y cómo desplegarlo
El proyecto La configuración, cómo extender la API y cómo desplegarla
Referencia Los comandos, las variables de entorno, los códigos de error y las novedades de cada versión