ViewSets — APIs REST CRUD
Un ViewSet convierte un modelo en un recurso REST completo — endpoints para listar, crear, leer, actualizar y eliminar registros — a partir de una sola declaración. Tú describes el modelo y el contrato que quieres; el enrutado, la paginación y la serialización los pone el framework.
¿Nuevo en las APIs REST? Esta guía asume que sabes qué es un endpoint, un verbo HTTP (GET / POST / …) y una petición y respuesta JSON. Si algo de eso te resulta confuso, el glosario es una introducción de cinco minutos — léelo primero y luego vuelve aquí.
Empareja un ViewSet con un serializador — la pieza que da forma a tu JSON — y protege ambas direcciones a la vez: el serializador formatea cada respuesta (renombra, oculta, calcula o anida campos) y gobierna cada petición (valida los datos entrantes e ignora silenciosamente los campos que un cliente no debería poder establecer). La entrada rechazada regresa con una forma fácil de leer — un objeto JSON indexado por nombre de campo. Todo funciona igual en PostgreSQL, MySQL y SQLite.
Esta guía es ante todo un tutorial: construimos una API REST de blog completa de principio a fin — scaffolding, modelos, un serializador, el ViewSet, los seis endpoints CRUD, validación de entrada, filtrado/búsqueda/paginación y pruebas — y luego el resto de la página es una referencia de cada perilla.
Fuente:
rustango::viewset(ViewSet,#[derive(ViewSet)], las opciones#[viewset(...)]+ el builderfor_model) — condicionado aadminotenancy. Dentro,.serializer::<S>()requiereserializer,tenant_router()/OwnedByrequierentenancy, y la acción QUERY requiereadmin.Versión ejecutable: el blog construido aquí refleja el ejemplo probado y compilable
getting_started_blog(susPost/PostSerializer/PostViewSet), y cada comportamiento está fijado por las propias pruebas en vivo del framework —crates/rustango/tests/viewset_*.rs(en particularviewset_serializer_render_sqlite_liveyviewset_serializer_input_sqlite_live).
Tabla de contenidos
- Vistas de API vs vistas HTML — ¿JSON para clientes o páginas HTML?
- Construir una API REST de blog — el recorrido completo
- El matrimonio con el serializador: entrada + salida
- Las dos formas de definir un ViewSet
- Los endpoints CRUD · Elegir cuáles exponer
- Referencia de
#[viewset(...)]· Referencia del builder - Filtrado, búsqueda y ordenación · Paginación
- Validación · Permisos y throttling · Acciones personalizadas
- Montaje · Backends
Vistas de API vs vistas HTML
Antes del tutorial, una bifurcación en el camino. Rustango tiene dos formas de convertir un modelo en endpoints, y un ViewSet es una de ellas:
- Un ViewSet (esta guía) es una vista de API — habla JSON, para frameworks de frontend, apps móviles y otros servicios.
- Una vista de plantilla (vistas HTML) es una vista HTML — renderiza páginas del lado del servidor a través de Tera, para navegadores y sitios renderizados en el servidor.
El mismo modelo por debajo; lo que difiere es qué sale y quién llama.
| Vista de API — ViewSet (aquí) | Vista HTML — vistas de plantilla | |
|---|---|---|
| Módulo | rustango::viewset | rustango::template_views |
| Devuelve | datos JSON | una página HTML renderizada en el servidor |
| Diseñado para | SPAs, móvil, otros servicios | navegadores, sitios renderizados en el servidor, CRUD estilo admin |
| Un "crear" | POST JSON → 201 + el objeto | POST de un formulario → redirección 303 (Post/Redirect/Get) |
| Ante entrada inválida | 400 ApiError; errores del serializador 422, campos en details | re-renderiza el formulario con los errores mostrados |
| Un "listar" es | un sobre JSON paginado | un bucle sobre filas en tu plantilla |
| Normalmente autenticado por | tokens / JWT / claves de API | cookies de sesión |
Elige por recurso — y puedes montar ambos sobre el mismo modelo (una API JSON pública y páginas CRUD internas). El resto de esta guía es el lado JSON/API; para el lado HTML consulta Vistas HTML — páginas renderizadas en el servidor.
Construir una API REST de blog
Construiremos un blog con dos modelos — Author y Post — y expondremos Post
como un recurso REST en /api/posts cuya forma JSON y validación están
gobernadas por un serializador. Al final podrás hacer curl a cada verbo CRUD y
ver cómo el serializador da forma a la salida y rechaza la entrada inválida.
Este recorrido asume un proyecto creado con cargo rustango new myblog
(consulta Primeros pasos para la configuración del proyecto
y la base de datos). Cada paso es un comando o archivo real.
Paso 1 — Crear la app del blog
Las apps son módulos de funcionalidad autocontenidos:
cargo run -- startapp blog
Eso escribe src/blog/{mod,models,views,urls,tests}.rs y conecta el módulo
dentro de src/lib.rs + el agregador urls::api().
Paso 2 — Definir los modelos
src/blog/models.rs — un Author y un Post (una clave foránea los enlaza):
use rustango::{Auto, Model};
use chrono::{DateTime, Utc};
#[derive(Model, Clone, Debug)]
#[rustango(table = "authors", display = "name")]
pub struct Author {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(max_length = 120)]
pub name: String,
#[rustango(max_length = 200)]
pub email: String,
}
#[derive(Model, Clone, Debug)]
#[rustango(table = "posts", display = "title", index("status, published_at"))]
pub struct Post {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(max_length = 200)]
pub title: String,
pub body: String,
#[rustango(max_length = 20, default = "'draft'")]
pub status: String, // draft | published | archived
#[rustango(fk = "authors", on = "id")]
pub author_id: i64,
#[rustango(auto_now_add)]
pub published_at: Auto<DateTime<Utc>>,
}
Paso 3 — Migrar
Genera y aplica la migración (igual que makemigrations + migrate):
cargo run -- makemigrations
cargo run -- migrate
Paso 4 — Generar el serializador
El serializador define el contrato de petición/respuesta de la API. Genera el esqueleto:
cargo run -- make:serializer PostSerializer --model Post
Luego complétalo. Este ejercita toda la superficie de entrada+salida — un renombrado, un campo calculado de solo lectura, un campo de servidor de solo lectura y un validador de campo:
// src/blog/post_serializer.rs
use rustango::{Auto, Serializer};
use chrono::{DateTime, Utc};
use crate::blog::models::Post;
#[derive(Serializer, serde::Deserialize, Default)]
#[serializer(model = Post)]
pub struct PostSerializer {
pub id: Auto<i64>,
#[serializer(validate = "title_min_3")] // input: reject titles < 3 chars
pub title: String,
#[serializer(source = "body")] // JSON key `content`, column `body`
pub content: String,
pub status: String,
pub author_id: i64,
#[serializer(method = "summary")] // output: computed, never written
pub summary: String,
#[serializer(read_only)] // output: shown, ignored on write
pub published_at: Auto<DateTime<Utc>>,
}
impl PostSerializer {
fn title_min_3(t: &String) -> Result<(), String> {
if t.chars().count() < 3 {
Err("title must be at least 3 characters".into())
} else {
Ok(())
}
}
fn summary(p: &Post) -> String {
p.body.chars().take(80).collect::<String>()
}
}
El generador escribe src/post_serializer.rs: muévelo a src/blog/post_serializer.rs
y añade pub mod post_serializer; a src/blog/mod.rs.
Nota que solo escribimos un validador (title_min_3); los campos también
heredan las restricciones del modelo automáticamente — a title se le
verifica la longitud contra el max_length = 200 del modelo, y una columna con
choices/min/max también se verificaría, todo devolviendo 422s amigables
en la escritura. Añade los atributos de serializador max_length / min_length /
min / max para sobrescribir el límite de un campo. (Consulta la
guía de serializadores para la historia completa de
validación.)
Paso 5 — Generar el ViewSet y conectar el serializador
cargo run -- make:viewset PostViewSet --model Post
Edítalo para declarar el recurso y conectar el serializador con el atributo
serializer — esa única línea activa la salida y la entrada gobernadas por
el serializador:
// src/blog/post_view_set.rs
use rustango::ViewSet;
use crate::blog::models::Post;
#[derive(ViewSet)]
#[viewset(
model = Post,
fields = "id, title, body, status, author_id, published_at",
serializer = crate::blog::post_serializer::PostSerializer,
filter_fields = "author_id, status",
search_fields = "title, body",
ordering = "-published_at",
page_size = 20,
allow_anonymous,
)]
pub struct PostViewSet;
El generador escribe src/post_view_set.rs, empieza como read_only e importa
Post desde crate::blog::models. Muévelo a src/blog/post_view_set.rs
como se muestra y añade pub mod post_view_set; a src/blog/mod.rs.
fieldses obligatorio: es la lista blanca de escritura, así que un body no puede fijar otra columna (por ejemploauthor_id). Un serializador la restringe más; nunca la amplía.
Paso 6 — Montar las rutas
startapp ya fusionó blog::urls::api() en urls::api(). Déjala como está: no
recibe pool. Genera en su lugar el compositor de la app que recibe el pool con
cargo run -- make:api_routes blog, y completa src/blog/api_routes.rs:
// src/blog/api_routes.rs
use axum::Router;
use rustango::sql::Pool;
pub fn api(pool: Pool) -> Router<()> {
Router::new()
.merge(crate::blog::post_view_set::PostViewSet::router("/posts", pool))
}
Añade pub mod api_routes; a src/blog/mod.rs. Luego móntalo en src/main.rs,
después de .api(urls::api()), donde el Cli le da el pool del servidor:
.nest_with("/api", |pool| myblog::blog::api_routes::api(pool)). El ViewSet
responde ahora en /api/posts. Anida el prefijo /api una sola vez: una ruta de
ViewSet que lo repita serviría /api/api/posts.
Paso 7 — Ejecutarlo y probar cada endpoint
Los posts apuntan a un autor (author_id es una clave foránea), así que carga
uno primero. Guarda esto como fixtures/authors.json:
[{"model": "Author", "pk": 1, "fields": {"name": "Ada", "email": "[email protected]"}}]
cargo run -- loaddata fixtures/authors.json
cargo run # listening on http://127.0.0.1:8080
Crear (POST). El serializador valida primero, luego escribe solo los campos
que acepta:
# happy path — note `content` (the renamed `body`) on the way in
curl -X POST localhost:8080/api/posts \
-H 'content-type: application/json' \
-d '{"title":"Hello Rustango","content":"First post body.","status":"published","author_id":1}'
{
"id": 1,
"title": "Hello Rustango",
"content": "First post body.",
"status": "published",
"author_id": 1,
"summary": "First post body.",
"published_at": "2026-01-02T12:00:00Z"
}
La respuesta tiene la forma del serializador: body regresó como content,
apareció el summary calculado, y published_at (de solo lectura, establecido
por el servidor) está presente.
La validación rechaza la entrada inválida con un 422 —
arreglos de mensajes indexados por campo bajo details:
curl -i -X POST localhost:8080/api/posts \
-H 'content-type: application/json' \
-d '{"title":"hi","content":"x","author_id":1}'
# HTTP/1.1 422 Unprocessable Entity
# {"error":"validation_failed","message":"invalid input","status":422,
# "details":{"title":["title must be at least 3 characters"]}}
Los campos de solo lectura / calculados que un cliente envía se ignoran — no
pueden inyectar published_at ni summary:
curl -X POST localhost:8080/api/posts \
-H 'content-type: application/json' \
-d '{"title":"Sneaky","content":"x","author_id":1,"published_at":"1999-01-01T00:00:00Z","summary":"hax"}'
# → published_at is the server value, not 1999; summary is recomputed from body.
Listar (GET) — paginado, cada fila con la forma del serializador:
curl localhost:8080/api/posts
{ "count": 1, "page": 1, "page_size": 20, "last_page": 1, "results": [ { "id": 1, "title": "Hello Rustango", … } ] }
Recuperar / actualizar / actualización parcial / eliminar:
curl localhost:8080/api/posts/1 # retrieve → 200
curl -X PUT localhost:8080/api/posts/1 -H 'content-type: application/json' \
-d '{"title":"Edited","content":"new body","status":"published","author_id":1}' # full update → 200
curl -X PATCH localhost:8080/api/posts/1 -H 'content-type: application/json' \
-d '{"title":"Just the title"}' # partial update → 200 (other fields untouched)
curl -X DELETE localhost:8080/api/posts/1 # destroy → 204
La validación de PATCH corre sobre lo que envías; los campos de solo lectura se
mantienen en su valor de servidor incluso si se envían.
Paso 8 — Filtrar, buscar, ordenar, paginar
Todo en el endpoint de listado, sin código adicional (declaraste los campos en el Paso 5):
curl 'localhost:8080/api/posts?status=published&author_id=1' # filter
curl 'localhost:8080/api/posts?status__in=published,archived' # lookup
curl 'localhost:8080/api/posts?search=rustango' # search title+body
curl 'localhost:8080/api/posts?ordering=title' # sort (asc)
curl 'localhost:8080/api/posts?page=2&page_size=10' # paginate
Paso 9 — Probarlo
El framework incluye un cliente de pruebas en proceso — haz aserciones sobre respuestas HTTP reales sin arrancar un servidor:
// tests/post_api.rs
use myblog::blog::models::Author;
use myblog::blog::post_view_set::PostViewSet;
use rustango::sql::Pool;
use rustango::test_client::TestClient;
use rustango::Auto;
use serde_json::json;
/// The router, and a fresh author for the posts to point at (`author_id`
/// is a foreign key, so an id with no row fails the insert).
async fn app() -> (TestClient, i64) {
// `cargo test` does not read `.env`; load it as main.rs does.
let _ = dotenvy::dotenv();
// `Pool::connect` picks the backend from the URL scheme, so the
// same test runs against sqlite, Postgres or MySQL.
let pool = Pool::connect(&std::env::var("DATABASE_URL").unwrap()).await.unwrap();
let mut author = Author {
id: Auto::default(),
name: "Test author".into(),
email: "[email protected]".into(),
};
author.save(&pool).await.unwrap();
let author_id = *author.id.get().unwrap();
(TestClient::new(PostViewSet::router("/api/posts", pool)), author_id)
}
#[tokio::test]
async fn rejects_short_title() {
let (client, author_id) = app().await;
let res = client.post("/api/posts")
.json(&json!({"title":"hi","content":"x","author_id":author_id}))
.send().await;
assert_eq!(res.status, 422);
assert!(res.json_value()["details"]["title"].is_array()); // field-keyed error shape
}
#[tokio::test]
async fn create_then_list() {
let (client, author_id) = app().await;
let created = client.post("/api/posts")
.json(&json!({"title":"Hello","content":"b","status":"published","author_id":author_id}))
.send().await;
assert_eq!(created.status, 201);
let list = client.get("/api/posts").send().await;
assert!(list.json_value()["results"].is_array());
}
cargo test --test post_api
Ese es un recurso REST completo y validado. El resto de esta página es la referencia detrás de cada paso.
El matrimonio con el serializador: entrada + salida
Conectar un serializador (vía serializer = … en el derive, o .serializer::<S>()
en el builder) cambia ambas direcciones. Funciona igual en PostgreSQL, MySQL
y SQLite.
Salida — las respuestas se renderizan a través del serializador
Las respuestas de list, retrieve, create y update se producen mediante
S::from_model(&row), de modo que las sobrescrituras del serializador dan forma
al JSON:
| Campo del serializador | Efecto en la respuesta |
|---|---|
#[serializer(source = "body")] | la columna body se emite bajo el nombre del campo (p. ej. content) |
#[serializer(method = "fn")] | aparece un campo calculado (a partir de Self::fn(&model)) |
#[serializer(read_only)] | incluido en la salida |
#[serializer(write_only)] | omitido de la salida |
Advertencia sobre
nested/many. Los campos de serializador anidados y de colección se renderizan solo cuando las filas relacionadas fueron cargadas (víaselect_related/ una carga anticipada); de lo contrario recurren a su valor por defecto. La consulta de listado del ViewSet automático carga la fila base — conecta las relaciones explícitamente si un campo anidado debe poblarse.
Entrada — las peticiones se validan y filtran
En create y update, cuando hay un serializador registrado:
- Se ejecuta la validación. El
validate()del serializador — cada#[serializer(validate = "fn")]por campo más elvalidatecruzado a nivel de contenedor — corre contra el cuerpo JSON. Ante un fallo, la petición se rechaza con422 Unprocessable Entity(validation_failed) con la forma de error indexada por campo endetails: un objeto JSON indexado por nombre de campo con arreglos de mensajes, p. ej.{"title":["title must be at least 3 characters"]}. - Filtrado de campos escribibles. Solo se persisten los campos escribibles
del serializador; los campos
read_onlyymethod/calculados que un cliente envía se ignoran (no se escriben), y los renombrados desourcese resuelven a la columna del modelo. Así, un cliente no puede establecer un campo controlado por el servidor incluyéndolo en el cuerpo.
Los cuerpos form-urlencoded (frente a JSON) omiten
validate()— no hay un valor tipado que validar — pero aún reciben el filtrado de campos escribibles.
Por debajo, esto son los métodos validate(), writable_source_fields() y
from_writable_json() del trait ModelSerializer, todos generados por
#[derive(Serializer)]. Consulta la guía de serializadores para
saber cómo escribir los validadores.
Las dos formas de definir un ViewSet
Ambas producen un axum::Router con las mismas rutas CRUD.
1. La macro derive — declarativa, de un solo inquilino; conecta un
serializador con serializer = …:
#[derive(ViewSet)]
#[viewset(
model = Post,
fields = "id, title, body, status, author_id, published_at",
serializer = crate::blog::post_serializer::PostSerializer,
filter_fields = "author_id, status",
search_fields = "title, body",
ordering = "-published_at",
page_size = 20,
allow_anonymous,
)]
pub struct PostViewSet;
let router = PostViewSet::router("/api/posts", pool);
2. El builder — ViewSet::for_model(...), programático, tri-dialecto
(PostgreSQL / SQLite / MySQL) y consciente de la tenencia; conecta un serializador
con .serializer::<S>():
use rustango::viewset::ViewSet;
use rustango::core::Model as _;
let router = ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"])
.serializer::<PostSerializer>()
.filter_fields(&["author_id", "status"])
.search_fields(&["title", "body"])
.ordering(&[("published_at", true)]) // true = DESC
.page_size(20)
.router("/api/posts", pool); // tri-dialect Pool
Recurre al builder cuando necesites SQLite/MySQL, multi-tenencia, una configuración construida en tiempo de ejecución, o los extras (throttling, backends de filtro personalizados, paginación por cursor).
Los endpoints CRUD
Montar en /api/posts conecta las seis operaciones REST:
| Verbo | Ruta | Acción | Éxito | Cuerpo |
|---|---|---|---|---|
GET | /api/posts | list | 200 | sobre paginado (ver Paginación) |
POST | /api/posts | create | 201 | el objeto creado — o un arreglo, para creación masiva |
GET | /api/posts/{pk} | retrieve | 200 | el objeto |
PUT | /api/posts/{pk} | update (completa) | 200 | el objeto actualizado |
PATCH | /api/posts/{pk} | partial update | 200 | el objeto actualizado (solo cambian los campos suministrados) |
DELETE | /api/posts/{pk} | destroy | 204 | vacío |
Una barra final en el prefijo de montaje es opcional. Solo se conectan estos seis
verbos, más una acción de colección QUERY (RFC 10008) cuando la característica
admin está activa. Las rutas se construyen con axum::routing::get, así que
axum responde al HEAD desde el handler GET; OPTIONS no está cableado. La creación masiva viene gratis:
haz POST de un arreglo JSON y cada elemento se inserta en orden, dentro de una
transacción. Un elemento inválido rechaza todo el lote y no deja nada atrás — lo
detecte la validación o la base de datos.
Esa segunda mitad no era cierta en versiones antiguas. La validación era atómica; las escrituras eran un
INSERTcada una sin transacción, así que una violación de unicidad o de clave foránea en el elemento 5 confirmaba los elementos 0–4, devolvía400 bulk entry 5y no nombraba ninguna de las filas creadas. Esas violaciones son justo la clase que la validación no puede decidir de antemano.
Un lote admite como mucho 1000 filas (max_bulk_create(n); más es un 413), y
cada fila gasta una unidad del throttle de create.
En un modelo #[rustango(soft_delete)], DELETE marca la columna en lugar de
borrar, y todas las acciones tratan una fila con borrado lógico como inexistente.
Elegir qué operaciones exponer
Para un recurso de solo lectura (solo list + retrieve), añade read_only:
#[viewset(model = Post, fields = "id, title", read_only)] // macro
ViewSet::for_model(Post::SCHEMA, &["id", "title"]).read_only() // builder
No hay un interruptor por verbo más allá de read-only. Para "todo excepto eliminar", monta el ViewSet y sobrescribe la única ruta con tu propio handler (ver Acciones personalizadas).
Referencia del atributo #[viewset(...)]
| Clave | Ejemplo | Por defecto | Qué hace |
|---|---|---|---|
model | model = Post | requerido | El modelo sobre el que se construye el recurso. |
serializer | serializer = path::To::S | ninguno | Conecta un serializador para salida + entrada tipadas (ver arriba). |
fields | "id, title, body" | obligatorio | Los únicos campos que las respuestas muestran y los bodies pueden escribir; las demás claves se ignoran. Un serializador la restringe. |
filter_fields | "author_id, status" | ninguno | Campos filtrables vía ?field=value (+ lookups). |
search_fields | "title, body" | ninguno | Campos con los que coincide la caja ?search= (OR sin distinción de mayúsculas). |
ordering | "-published_at, id" | ninguno | Orden por defecto (- = DESC). |
page_size | 20 | 20 | Filas por página (el ?page_size= del cliente se limita a 100). |
read_only | (flag) | apagado | Expone solo GET (list + retrieve). |
allow_anonymous | (flag) | apagado | Indica que las acciones de escritura sin codenames deben ser abiertas; sin él (ni read_only) no se montan. |
permissions(...) | permissions(create = "posts.add") | ninguno | Codenames de permiso por acción; requiere tenancy. |
Referencia del builder
ViewSet::for_model(SCHEMA, &["id", "title"]) recibe la lista de campos: los únicos
que las respuestas muestran y los bodies pueden escribir. Cada otro método devuelve Self:
| Método | Propósito |
|---|---|
serializer::<S>() | Conecta un serializador para salida + entrada tipadas (tri-dialecto). |
filter_fields(&["…"]) | Habilita el filtrado ?field=value. |
search_fields(&["…"]) | Habilita ?search=. |
ordering(&[("field", desc)]) | Orden de clasificación por defecto. |
ordering_fields(&["…"]) | Lista blanca de qué campos puede usar ?ordering=. |
page_size(n) | Tamaño de página por defecto (≤ 100). |
max_page_size(n) | Sube o baja el propio tope del cliente (100 por defecto). |
max_offset(n) | Fila más profunda para ?offset= / ?page=; por encima un 400 (10 000 por defecto, 0 lo quita). |
count(false) | Omite el COUNT(*); count es entonces null. |
pk_param(name) | Renombra el parámetro de ruta de las rutas de detalle (pk_param_name() lo lee). |
openapi_query(bool) | Describe la ruta QUERY en el documento OpenAPI generado (necesita herramientas de OpenAPI 3.2). Apagado por defecto; la ruta se monta igualmente. |
related_filter(fk_field, backend) | Limita qué filas destino puede nombrar una FK del cuerpo; cualquier otra es un 422. |
read_only() | Solo GET. |
allow_anonymous() | Las escrituras sin codenames son intencionadas; sin él no se montan. |
max_bulk_create(n) | Máximo de filas que puede llevar una creación masiva (1000 por defecto). |
permissions(ViewSetPerms{…}) / permissions_for_model::<T>() | Compuertas de codename por acción; ambas requieren tenancy. |
cursor_pagination("id") / cursor_pagination_desc("id") | Paginación por keyset (omite COUNT(*)). Cualquier columna NOT NULL de orden total: entero, timestamp, fecha, uuid o cadena. |
limit_offset_pagination() | Ventaneo ?limit=&offset=. |
pagination(PaginationStyle::…) | Establece el estilo explícitamente. |
filter_backend(closure) | Añade predicados WHERE personalizados más allá de filter_fields. |
throttle(…) / throttle_all(max, secs) | Límites de tasa de ventana fija por acción; QUERY gasta el presupuesto de list. |
skip_object_permissions() | Omite los hooks de permiso por objeto y los scopes de queryset de la app, para una API que protege sus filas por su cuenta. Los hooks del framework siguen ejecutándose. |
view_hook_scan_cap(n) | Máximo de filas que una lista lee para el hook "view" (2 000 por defecto, 10 000 en el admin; como mucho 100 000); por encima, una lista por página u offset es un 400 (el modo cursor sigue funcionando). Un campo de serializer nested / many / slug hacia una tabla con hook view o scope de queryset hace fallar el montaje, salvo con skip_object_permissions(). |
router(prefix, pool) | Monta tri-dialecto (PG / SQLite / MySQL). |
tenant_router(prefix) | (tenencia) monta con resolución de inquilino por petición. |
Filtrado, búsqueda y ordenación
Todo gobernado por parámetros de consulta en el endpoint de listado.
Filtrado — cada entrada de filter_fields acepta ?field=value (exacto) más
lookups vía un sufijo __:
?status=published
?author_id__in=1,2,3
?published_at__gte=2026-01-01
?title__icontains=rust
?body__isnull=false
Lookups soportados: iexact, ne, gt, gte, lt, lte, in, not_in,
range (lo,hi), contains, icontains, startswith, istartswith,
endswith, iendswith, isnull, y las partes de fecha year, month, day,
hour, minute, second, quarter, week, week_day, date, seguidas
opcionalmente de una comparación (created_at__date__gte=2026-01-01). Sin
sufijo = exacto. Una fecha simple en un __gte / __lte sobre un datetime cubre
todo ese día UTC.
Un valor vacío no filtra. Un lookup desconocido o un valor que no se puede
interpretar es un 400 que nombra el parámetro; con un filter_backend
registrado, un lookup desconocido se deja al backend. Los lookups LIKE necesitan
un campo de texto. Los campos que no están en filter_fields se ignoran.
Búsqueda — ?search=term coincide con search_fields mediante un OR sin
distinción de mayúsculas.
Ordenación — ?ordering=field,-other (- = DESC). Cualquier campo que la
respuesta muestra (con un serializador, los campos que renderiza) es ordenable a menos que establezcas .ordering_fields([...]) para restringirlo. Sin
un parámetro, se aplica el ordering por defecto, o si no el default_order del
modelo; la clave primaria siempre desempata. Todos se componen.
Paginación
Trampa — pagina sobre un orden determinista. La paginación por número de página y por limit/offset asume una clasificación estable; ordenar por una columna no única (o por ninguna) permite que las filas se desplacen entre páginas — duplicadas u omitidas. Añade siempre un desempate único, p. ej.
ordering = "-published_at, id". (Ambas también ejecutanCOUNT(*)por llamada; la paginación por cursor lo omite para tablas grandes.)
Tres estilos; el de número de página es el predeterminado. El sobre de listado difiere según el estilo:
Número de página (por defecto) — ?page=2&page_size=20:
{ "count": 137, "page": 2, "page_size": 20, "last_page": 7, "results": [ … ] }
Cursor — .cursor_pagination("id") (o _desc); omite COUNT(*), ideal para
tablas muy grandes. El campo debe tener un orden total: un entero, timestamp,
fecha, uuid o cadena. "id" es la elección habitual; un timestamp created_at
es la otra, y es lo que quieres en una tabla de solo inserción. Una columna
float, bool, json o blob provoca un panic al construir en lugar de fallar en cada
petición. ?cursor=<token>&page_size=20:
{ "page_size": 20, "next": "<opaque-cursor-or-null>", "results": [ … ] }
Limit/offset — .limit_offset_pagination(). ?limit=20&offset=40:
{ "count": 137, "limit": 20, "offset": 40, "results": [ … ] }
page_size / limit se limitan a max_page_size (100 por defecto).
Validación
Con un serializador conectado, la ruta de create/update ejecuta los
validadores del serializador y devuelve 422s indexados por campo — la forma
recomendada de validar (ver el matrimonio
y la guía de serializadores). Se ejecutan tres capas:
- Restricciones declarativas —
max_length/min_length/min/max, y por defecto el campo hereda del modelomax_length/min/max/choices. Así, una columna#[rustango(max_length = 200)]se verifica en longitud en la API sin configuración extra, convirtiendo los500s que serían por restricción de BD en422s amigables condetailscomo{"title":["Ensure this value has at most 200 characters."]}. - Por campo
validate = "fn"y un hookvalidatecruzado — tus reglas personalizadas (formatos, entre campos, lógica de negocio).
Independientemente de un serializador, la ruta de escritura siempre aplica el esquema:
- Los tipos se coaccionan y verifican — un valor
i64/DateTime/Uuid/boolinválido es un400que nombra el campo. - Requerido / NOT NULL — un campo no anulable faltante (o cadena vacía para un
Stringno anulable) es un400; los campos anulables aceptan vacío →NULL. En un cuerpo JSON solonullesNULL:""en unStringanulable sigue siendo"". - Números — NaN e infinito dan un
400; un decimal enviado como número JSON conserva todos sus dígitos. - Restricciones de base de datos — una clave duplicada es un
409(conflict); las claves foráneas y las restricciones check afloran como un400en INSERT/UPDATE.
Así que incluso sin un serializador obtienes validación de tipo + requerido + restricción de BD; conecta un serializador para obtener verificaciones declarativas de longitud/rango/choice (heredadas automáticamente) más tus propias reglas por campo y entre campos.
Formas de respuesta de error
Todo error de un ViewSet es un cuerpo ApiError, la misma
forma que envían tus propios handlers:
{"error": "<machine code>", "message": "<sentence>", "status": 400}
errores un código estable (bad_request,unauthorized,not_found,validation_failed,rate_limited,internal_error, …). Ramifica según él.- La validación del serializador es un
422validation_failed, con el mapa por campo endetails:{"title": ["Ensure this value has at most 200 characters."], "non_field_errors": [ … ]}. Los400de coerción de tipos y de campo requerido de arriba sonbad_request, con el motivo enmessage; un400de restricción de base de datos oculta el texto del driver. - Un
5xxnunca lleva la causa salvo queRUSTANGO_DISCLOSE_ERRORSesté definida. Se registra en el log;messagees genérico.
Permisos y throttling
Las lecturas son públicas por defecto; las escrituras no. Un ViewSet sin codenames sirve list y retrieve a cualquiera y no se monta mientras create, update o destroy no tengan ninguno, salvo con
read_onlyoallow_anonymous.
Los permisos protegen cada acción con codenames (OR dentro de una acción):
use rustango::viewset::{ViewSet, ViewSetPerms};
ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"])
.permissions(ViewSetPerms {
list: vec!["posts.view".into()],
retrieve: vec!["posts.view".into()],
create: vec!["posts.add".into()],
update: vec!["posts.change".into()],
destroy: vec!["posts.delete".into()],
})
.tenant_router("/api/posts");
En tenant_router el usuario debe pertenecer al tenant enrutado. En un
.router(prefix, pool) con pool fijo solo cuenta un usuario que tu propia capa
de auth de base única puso en la petición; el usuario de un tenant (require_auth,
una sesión) recibe 403. Con tenancy, monta los ViewSets protegidos con tenant_router.
Una lista de acción vacía = sin verificación. La aplicación lee un usuario
autenticado de la petición (la integración de autenticación de tenancy); los
superusuarios la eluden, un usuario ausente se deniega. .permissions_for_model::<Post>()
autocompleta los codenames estándar <table>.view / .add / .change /
.delete (posts.view, … para la tabla posts). Los codenames requieren la
feature tenancy: sin ella, un ViewSet que los fije se niega a montarse, con un
panic que indica la solución. En una app de una sola base, pon tu propia capa de
auth delante y usa allow_anonymous, o read_only. Primeros pasos, Paso 14
muestra esa capa completa: lectura pública, escrituras con token Bearer.
Permisos por objeto. Un ViewSet ejecuta los mismos hooks que el admin
(register_object_permission!, register_queryset_scope!): add al crear (un
bulk create es todo o nada, 403 con {"details": {"index": i}}); view al
leer, actualizar y eliminar (oculto es 404), luego change o delete (403,
también con soft delete); view en listas (las filas ocultas salen de la página
y del count; por encima de view_hook_scan_cap, una lista por página u offset
es un 400: añade un scope de queryset o usa paginación por cursor). Los scopes de queryset acotan cada lectura y escritura; una escritura cuya fila saldría de ellos es un 403, igual que una creación que el hook view ocultaría. Los hooks leen la fila bloqueada en la transacción de escritura; una credencial de otro tenant es un 403. change solo
comprueba la fila guardada. object_permissions::Actor::of(&parts) le dice a un
hook quién pregunta; un token de agente nunca es superuser. ViewSet::for_model
y las cinco vistas de plantilla rechazan rustango_api_keys, rustango_agents, rustango_agent_grants,
rustango_operators, rustango_admin_users y las tablas SSO.
El throttling aplica límites de ventana fija por cliente, por acción:
ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"])
.throttle_all(60, 60) // 60 requests / 60s per client, every action
.router("/api/posts", pool);
Sobre el límite → 429 Too Many Requests + Retry-After. Los contadores son por
proceso; la clave del cliente es la IP de cliente de confianza (TrustedRealIp,
si no el socket; ver security.md).
Con tenant_router cada inquilino tiene sus propios presupuestos.
Acciones personalizadas más allá de CRUD
No hay ningún atributo para añadir rutas extra a un ViewSet — es estrictamente las seis rutas CRUD. Para endpoints adicionales, monta tus propios handlers junto al ViewSet:
use axum::{Router, routing::{get, post}};
let api = Router::new()
.merge(ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"]).router("/api/posts", pool.clone()))
.route("/api/posts/stats", get(post_stats))
.route("/api/posts/bulk_archive", post(bulk_archive));
Para lógica WHERE adicional, .filter_backend(…) aporta predicados sin una ruta
separada.
Acotar filas al principal autenticado
Un backend se ejecuta en cada acción — list, retrieve, update,
destroy — de modo que acota el queryset base de todas las rutas. Una fila que
el backend excluye es un 404 en las rutas de ítem, no un 403: un 403
confirmaría que el id existe.
La identidad debe provenir de la credencial, nunca de la cadena de consulta. Un
filtro ?owner_id= no es un ámbito — es un parámetro que el llamador elige.
Un ámbito solo restringe la lectura. Un backend dueño de una columna implementa también
write_pins: la creación guarda el propietario, la actualización no puede cambiarlo, y
WritePin::Deny rechaza la escritura con un 403.
Los ámbitos globales estáticos de un modelo también limitan lo que se lee, no lo que se
escribe: una creación o actualización puede salir del ámbito (201 solo con la clave, o 204).
Para una frontera de seguridad, usa un backend de filtro con write_pins.
Una escritura devuelve su fila completa solo a quien tiene el permiso retrieve;
los demás reciben solo {"<pk>": …} (uno por fila en una creación masiva). Una
creación individual también envía una cabecera Location que apunta a la ruta
de detalle.
Una FK que fija un body debe nombrar una fila que muestren los ámbitos globales del destino; una actualización puede reenviar el valor que la fila ya tiene. Para restringirla más, añade un backend para ese campo; se ejecuta contra el modelo de destino, y cualquier otra fila es un 422:
ViewSet::for_model(Comment::SCHEMA, &["id", "body", "post_id"])
.related_filter("post_id", OwnedBy::column("author_id"))
OwnedBy — el backend incluido
La mayoría de los recursos con dueño necesitan exactamente una regla: filas cuya columna de propiedad es el llamador. Nombra la columna y móntala.
use rustango::tenancy::auth_routes::{require_bearer, Config, JwtAuth};
use rustango::viewset::{OwnedBy, ViewSet};
let auth = JwtAuth::new(Config::default()); // uno solo, que también sirve `auth.router()`
ViewSet::for_model(Note::SCHEMA, &["id", "body"])
.filter_backend(OwnedBy::column("member_id"))
.tenant_router("/api/notes")
.layer(axum::middleware::from_fn_with_state(auth.clone(), require_bearer))
Cualquier columna funciona — owner_id, member_id, author_id — porque el
backend toma el nombre en lugar de asumir una convención. Falla cerrado en las dos
formas en que puede estar mal: una petición no autenticada y una columna que el
modelo no tiene coinciden ambas con nada, de modo que un error tipográfico al
montar no puede convertirse en "sin predicados, devuelve la tabla".
OwnedBy fija su columna al escribir: la creación guarda al llamador diga lo que diga el
cuerpo, la actualización nunca mueve la fila, y una escritura sin principal es un 403.
Los superusuarios no son especiales por defecto; .superuser_sees_all() lo
habilita, porque "los admins ven todo" es una decisión de producto, no del
framework.
De dónde viene la identidad
[Principal] es el único tipo de identidad, resuelto a partir de lo que sea que
verificó la petición — un Principal explícito, un AuthenticatedUser dejado por
un middleware de sesión o Bearer, o un token de agente MCP (que actúa como el
usuario que lo acuñó). No autentica nada por sí mismo; solo lee lo que un
middleware verificador ya demostró, de modo que nada puede insertar uno sin
verificar primero una credencial.
require_bearer es ese middleware para una API JSON: verifica el token de acceso
contra el inquilino resuelto, vuelve a leer la fila del usuario (una cuenta
desactivada deja de funcionar en la siguiente petición, no cuando el token
expira), e inserta tanto AuthenticatedUser como Principal. Úsalo como
extractor en cualquier lugar:
use rustango::tenancy::{OptionalPrincipal, Principal};
async fn mine(principal: Principal) -> String { // 401 when absent
format!("user {}", principal.user_id)
}
async fn home(OptionalPrincipal(who): OptionalPrincipal) -> String {
who.map_or("anonymous".into(), |p| format!("user {}", p.user_id))
}
Escribir tu propio backend
Cuando la propiedad no es una sola columna — un equipo compartido, una fila con
borrado lógico, una ventana de fechas — implementa el trait y sobrescribe
filter_with, que recibe los Parts de la petición:
use std::collections::HashMap;
use axum::http::request::Parts;
use rustango::core::{Filter, ModelSchema, Op, SqlValue, WhereExpr};
use rustango::tenancy::Principal;
use rustango::viewset::{match_nothing, ViewSetFilter};
struct OwnerFilter;
impl ViewSetFilter for OwnerFilter {
// No principal in hand — fail closed. `vec![]` here would be *no filter*,
// not a filter matching nothing, and would widen the query to every row.
fn filter(&self, _p: &HashMap<String, String>, schema: &'static ModelSchema) -> Vec<WhereExpr> {
vec![match_nothing(schema)]
}
fn filter_with(
&self,
parts: &Parts,
_p: &HashMap<String, String>,
schema: &'static ModelSchema,
) -> Vec<WhereExpr> {
let Some(principal) = Principal::from_parts(parts) else {
return vec![match_nothing(schema)];
};
vec![WhereExpr::Predicate(Filter::new(
schema.field("owner_id").expect("owner_id").column,
Op::Eq,
SqlValue::from(principal.user_id),
))]
}
}
ViewSet::for_model(Note::SCHEMA, &["id", "body"])
.filter_backend(OwnerFilter)
.tenant_router("/api/notes")
filter_with recae por defecto en filter, de modo que un backend que no
necesita la petición — incluida la forma de closure simple — implementa solo
filter como antes.
match_nothing es la rama de fallo cerrado, y conviene usarla en lugar de
escribirla a mano: devuelve col IS NULL AND col IS NOT NULL, una contradicción
que no vincula parámetros y se lee igual en todos los backends. La razón de que
esté exportada es que el sustituto obvio es un Vec vacío, y en una API de
filtros vec![] significa ningún filtro — lo contrario de para lo que existe
la rama.
Montaje
Compón el router del ViewSet en tu app. Un solo inquilino, pool estático:
let api = urls::api()
.merge(PostViewSet::router("/api/posts", pool.clone())) // macro
.merge(ViewSet::for_model(Author::SCHEMA, &["id", "name"]).router("/api/authors", pool.clone())); // builder
Multi-inquilino (sin pool capturado — cada petición resuelve su conexión de inquilino):
let api = urls::api()
.merge(ViewSet::for_model(Post::SCHEMA, &["id", "title", "body"]).tenant_router("/api/posts"));
make:api_routes <app> genera una api() por app que reúne estas líneas
.merge(...). Recibe el pool, así que móntala desde main.rs con
.nest_with("/api", |pool| myapp::<app>::api_routes::api(pool)); la de
--tenant no recibe ninguno y se une en urls.rs.
Soporte de backends
- El builder +
router/tenant_routeres tri-dialecto — PostgreSQL, SQLite y MySQL — y es la ruta recomendada. - El
router(prefix, pool)de la macro derive recibeimpl Into<rustango::sql::Pool>— unPgPool,MySqlPool,SqlitePoolo el enumPool. No es exclusivo de Postgres. - La entrada + salida del serializador ahora funciona en los tres backends (el renderizado por fila es tri-dialecto; la antigua compuerta solo-PG desapareció).
- El filtrado, la búsqueda, la ordenación, los tres modos de paginación, los permisos, el throttling y la creación masiva funcionan todos en los backends soportados en la ruta del builder.
Pruébalo
El flujo de principio a fin de arriba refleja el ejemplo compilable
getting_started_blog (Pasos 12–13 de la guía de primeros pasos).
Las propias pruebas en vivo del framework bajo crates/rustango/tests/viewset_*.rs
son la referencia ejecutable más completa — incluidas las pruebas de
entrada/salida del serializador. Corren sobre SQLite en memoria pero necesitan los
feature flags correspondientes, p. ej.:
cd crates/rustango
cargo test --features sqlite,tenancy --test viewset_serializer_render_sqlite_live
cargo test --features sqlite,tenancy --test viewset_serializer_input_sqlite_live
cargo test --features sqlite,tenancy --test viewset_sqlite_live
Véase también
- Serializadores — da forma al JSON que un ViewSet envía y valida.
- Vistas HTML — la contraparte renderizada en el servidor de esta API JSON.
- OpenAPI — genera una especificación + Swagger UI a partir de tus ViewSets.
- URLs y enrutamiento — compón routers de ViewSet en tu app.
![Un ViewSet de Rustango conectado a un serializador: un solo bloque #[viewset(serializer = …)] da salida JSON tipada y entrada validada en las seis rutas CRUD](/static/img/viewsets.png)