Saltar a contenido

Tu primera API

De un schema de tai-sql a una API con login y permisos. Se da por hecho que tienes un proyecto de tai-sql con un schema public —si no, empieza por el primer proyecto de tai-sql— y una base de datos PostgreSQL.

mi-proyecto/
└── database/        ← el proyecto de tai-sql, con schemas/public.py

1. Crear el proyecto de la API

Desde mi-proyecto/:

tai-api init mi-api --install

Crea api/ —el nombre de la carpeta es el namespace, api por defecto— con su .taiapiproject, su pyproject.toml, el paquete Python y un dockerfile. Ver El proyecto por dentro.

2. Generar los endpoints

export MAIN_DATABASE_URL=postgresql://usuario:clave@localhost:5432/midb
tai-api generate

La primera vez pregunta qué schemas generar; después recuerda la respuesta (generated_schemas del .taiapiproject). Escribe el cliente de tai-sql en api/database/public/, los endpoints en api/routers/database/public/ y el diagrama entidad-relación.

3. Arrancar sin autenticación

tai-api dev

La API está en http://localhost:8000, con la documentación en /docs y el diagrama en /docs/diagrams. Sin autenticación configurada, todos los endpoints están abiertos.

curl 'http://localhost:8000/public/usuario?limit=5'

4. Añadir autenticación

tai-api auth init

Pregunta el modo:

Los usuarios, los roles y los permisos viven en un schema auth de tu propia base de datos, que tai-api crea en el proyecto de tai-sql.

export SECRET_KEY=una-clave-larga-y-aleatoria
tai-sql push -s auth --with-feed     # crea las tablas, y el usuario admin/admin

Los usuarios viven en Keycloak. tai-api auth init configura el realm main.

export MAIN_KEYCLOAK_URL=http://admin:admin@localhost:8090
export KEYCLOAK_API_CLIENT_SECRET=el-secreto-del-cliente-api

Además crea rbac/main.py, la declaración de permisos del realm main.

5. Declarar los permisos

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

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

role(name="Administrador", api_permissions=["sudo", "main-admin"])
role(name="lector", api_permissions=["usuario-read", "post-read"])

source() registra los permisos de cada tabla del schema (post-read, post-create…), y cada role() los agrupa. Se llevan al backend con:

tai-api rbac push

Ver Permisos y roles.

6. Arrancar con autenticación

tai-api generate
tai-api dev --auth

curl -X POST http://localhost:8000/auth/main/login \
     -H 'Content-Type: application/json' -d '{"username": "admin", "password": "admin"}'
# → data.access_token

curl http://localhost:8000/public/usuario -H "Authorization: Bearer <access_token>"

Sin token, 401; con un token sin el permiso, 403. La documentación en /docs pide ahora usuario admin y la contraseña de API_DOCS_PWD.

Cambia la contraseña del admin

En modo Database, el usuario admin se crea con la contraseña de ADMIN_PWD, o admin si no está definida. Cámbiala antes de desplegar: POST /auth/me/password con {"current_password": "admin", "new_password": "…"}.

Siguientes pasos