Rustango docs
← Guías

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.

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

Fuente: rustango::viewset (ViewSet, #[derive(ViewSet)], las opciones #[viewset(...)] + el builder for_model) — condicionado a admin o tenancy. Dentro, .serializer::<S>() requiere serializer, tenant_router() / OwnedBy requieren tenancy, y la acción QUERY requiere admin.

Versión ejecutable: el blog construido aquí refleja el ejemplo probado y compilable getting_started_blog (sus Post / PostSerializer / PostViewSet), y cada comportamiento está fijado por las propias pruebas en vivo del framework — crates/rustango/tests/viewset_*.rs (en particular viewset_serializer_render_sqlite_live y viewset_serializer_input_sqlite_live).


Tabla de contenidos


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ódulorustango::viewsetrustango::template_views
Devuelvedatos JSONuna página HTML renderizada en el servidor
Diseñado paraSPAs, móvil, otros serviciosnavegadores, sitios renderizados en el servidor, CRUD estilo admin
Un "crear"POST JSON → 201 + el objetoPOST de un formulario → redirección 303 (Post/Redirect/Get)
Ante entrada inválida400 ApiError; errores del serializador 422, campos en detailsre-renderiza el formulario con los errores mostrados
Un "listar" esun sobre JSON paginadoun bucle sobre filas en tu plantilla
Normalmente autenticado portokens / JWT / claves de APIcookies 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.

fields es obligatorio: es la lista blanca de escritura, así que un body no puede fijar otra columna (por ejemplo author_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 serializadorEfecto 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ía select_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:

  1. Se ejecuta la validación. El validate() del serializador — cada #[serializer(validate = "fn")] por campo más el validate cruzado a nivel de contenedor — corre contra el cuerpo JSON. Ante un fallo, la petición se rechaza con 422 Unprocessable Entity (validation_failed) con la forma de error indexada por campo en details: un objeto JSON indexado por nombre de campo con arreglos de mensajes, p. ej. {"title":["title must be at least 3 characters"]}.
  2. Filtrado de campos escribibles. Solo se persisten los campos escribibles del serializador; los campos read_only y method/calculados que un cliente envía se ignoran (no se escriben), y los renombrados de source se 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:

VerboRutaAcciónÉxitoCuerpo
GET/api/postslist200sobre paginado (ver Paginación)
POST/api/postscreate201el objeto creado — o un arreglo, para creación masiva
GET/api/posts/{pk}retrieve200el objeto
PUT/api/posts/{pk}update (completa)200el objeto actualizado
PATCH/api/posts/{pk}partial update200el objeto actualizado (solo cambian los campos suministrados)
DELETE/api/posts/{pk}destroy204vací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 INSERT cada 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ía 400 bulk entry 5 y 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(...)]

ClaveEjemploPor defectoQué hace
modelmodel = PostrequeridoEl modelo sobre el que se construye el recurso.
serializerserializer = path::To::SningunoConecta un serializador para salida + entrada tipadas (ver arriba).
fields"id, title, body"obligatorioLos ú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"ningunoCampos filtrables vía ?field=value (+ lookups).
search_fields"title, body"ningunoCampos con los que coincide la caja ?search= (OR sin distinción de mayúsculas).
ordering"-published_at, id"ningunoOrden por defecto (- = DESC).
page_size2020Filas por página (el ?page_size= del cliente se limita a 100).
read_only(flag)apagadoExpone solo GET (list + retrieve).
allow_anonymous(flag)apagadoIndica que las acciones de escritura sin codenames deben ser abiertas; sin él (ni read_only) no se montan.
permissions(...)permissions(create = "posts.add")ningunoCodenames 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étodoPropó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 ejecutan COUNT(*) 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 modelo max_length / min / max / choices. Así, una columna #[rustango(max_length = 200)] se verifica en longitud en la API sin configuración extra, convirtiendo los 500s que serían por restricción de BD en 422s amigables con details como {"title":["Ensure this value has at most 200 characters."]}.
  • Por campo validate = "fn" y un hook validate cruzado — 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 / bool inválido es un 400 que nombra el campo.
  • Requerido / NOT NULL — un campo no anulable faltante (o cadena vacía para un String no anulable) es un 400; los campos anulables aceptan vacío → NULL. En un cuerpo JSON solo null es NULL: "" en un String anulable 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 un 400 en 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}
  • error es 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 422 validation_failed, con el mapa por campo en details: {"title": ["Ensure this value has at most 200 characters."], "non_field_errors": [ … ]}. Los 400 de coerción de tipos y de campo requerido de arriba son bad_request, con el motivo en message; un 400 de restricción de base de datos oculta el texto del driver.
  • Un 5xx nunca lleva la causa salvo que RUSTANGO_DISCLOSE_ERRORS esté definida. Se registra en el log; message es 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_only o allow_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_router es tri-dialecto — PostgreSQL, SQLite y MySQL — y es la ruta recomendada.
  • El router(prefix, pool) de la macro derive recibe impl Into<rustango::sql::Pool> — un PgPool, MySqlPool, SqlitePool o el enum Pool. 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.