← Primeros pasos

Glosario

Una referencia en lenguaje sencillo de las palabras usadas en esta documentación. Si un término de una guía te resulta desconocido, búscalo aquí primero. Las definiciones son deliberadamente informales — las guías en profundidad tienen los detalles precisos.

Si nunca has construido una API web antes, lee Fundamentos de las API web de principio a fin; es una introducción de cinco minutos. Todo lo demás está pensado para consultarse sobre la marcha.

Tabla de contenidos

Fundamentos de las API web — qué es una API, en términos cotidianos
Bloques de construcción de Rustango — las piezas que ensamblas
Los datos y la base de datos
Multi-tenancy — solo si sirves a varios clientes desde un único despliegue
Unas pocas palabras de Rust — para que los bloques de código no den miedo
Frameworks con los que comparamos

Fundamentos de las API web

API — Application Programming Interface (interfaz de programación de aplicaciones). Una forma de que un programa hable con otro. Una API web lo hace por internet: tu app envía un mensaje, el servidor envía uno de vuelta. Piénsalo como un camarero — pides de un menú, la cocina te devuelve comida.

API REST — el estilo más común de API web. "REST" es solo un conjunto de convenciones: actúas sobre recursos (como "posts" o "users") usando verbos web estándar. No necesitas conocer la teoría — en la práctica significa URL predecibles y un puñado de verbos, descritos a continuación.

Endpoint — una URL específica a la que responde tu API, como /api/posts (todos los posts) o /api/posts/42 (el post con id 42). Una API es una colección de endpoints.

Verbo HTTP (o método) — qué quieres hacer en un endpoint. Hay cinco que verás constantemente:

Verbo	Significa	Ejemplo
`GET`	leer / obtener	"dame todos los posts"
`POST`	crear	"añade un post nuevo"
`PUT`	reemplazar	"sobrescribe el post 42 por completo"
`PATCH`	actualizar parcialmente	"cambia solo el título del post 42"
`DELETE`	eliminar	"elimina el post 42"

Petición / Respuesta (request / response) — una petición es el mensaje que envías (un verbo + un endpoint

opcionalmente un cuerpo de datos). La respuesta es lo que vuelve (un código de estado + normalmente un cuerpo de datos).

JSON — el formato de texto que las API usan para transportar datos. Se ve como {"title": "Hello", "published": true} — valores etiquetados, legibles por humanos. Tanto las peticiones como las respuestas suelen ser JSON.

Código de estado (status code) — un número de tres dígitos en cada respuesta que indica cómo fue:

Código	Significado
`200`	OK — aquí están tus datos
`201`	Created — tu cosa nueva se guardó
`204`	Done — nada que devolver (p. ej. tras un borrado)
`400`	Bad request — enviaste algo inválido (el cuerpo dice qué)
`401` / `403`	No autenticado / no permitido
`404`	Not found (no encontrado)
`429`	Too many requests — ve más despacio
`500`	El servidor topó con un error

CRUD — Create, Read, Update, Delete (crear, leer, actualizar, eliminar). Las cuatro cosas básicas que haces con los datos. Una "API CRUD" simplemente significa una API que te permite hacer las cuatro. Consulta ViewSets, que construyen una API CRUD completa a partir de una sola declaración.

Cadena de consulta / parámetro de consulta (query string / query parameter) — la parte ?key=value al final de una URL, usada para filtrar, buscar, ordenar o paginar los resultados — p. ej. /api/posts?status=published&page=2. Cada key=value es un parámetro.

Paginación — dividir una lista larga de resultados en páginas para que una respuesta no sea enorme. El envelope (envoltorio) es lo que rodea a la página y también te indica los totales — p. ej. {"count": 137, "page": 2, "results": [ … ]}. Consulta Paginación.

curl — una herramienta de línea de comandos para enviar peticiones a la API a mano. Los ejemplos curl ... de esta documentación te permiten probar un endpoint desde una terminal sin escribir nada de código.

Bloques de construcción de Rustango

Estas son las piezas que ensamblas para construir una app. Cada una enlaza a su guía completa.

Modelo (Model) — una descripción de un tipo de cosa que tu app almacena, como un Post o un User. Lo escribes como un struct de Rust; Rustango lo convierte en una tabla de base de datos. Consulta la guía del ORM.

Migración (Migration) — un cambio registrado en la forma de tu base de datos (añadir una tabla, una columna…). Generas una con makemigrations y la aplicas con migrate, para que cada entorno acabe con la misma estructura de base de datos.

Serializer — el traductor entre las filas de tu base de datos y el JSON que tu API envía y recibe. Decide qué campos son visibles, renombra o calcula campos para la salida, y valida los datos entrantes. Da forma a los datos; no los guarda (eso lo hace el modelo). Consulta la guía de Serializers.

ViewSet — toma un modelo y un serializer y produce una API JSON CRUD completa (los cinco verbos de arriba) automáticamente, para que no escribas cada endpoint a mano. La vista de API. Consulta la guía de ViewSets.

Vista HTML (template view, class-based view) — la contraparte renderizada en el servidor de un ViewSet: convierte un modelo en páginas HTML — una página de lista, una página de detalle, y formularios de crear/editar/eliminar — renderizadas mediante plantillas Tera, en lugar de JSON. La vista HTML. Consulta Vistas HTML.

Plantilla (Template) — un archivo con marcadores de posición (Rustango usa Tera, muy parecido a Jinja) que el servidor rellena con datos para producir una página HTML. {{ post.title }} inserta un valor; {% for … %} itera.

Router / montaje (mount) — el router mapea las URL entrantes al código que las maneja. Montar un ViewSet significa "adjuntar sus endpoints a tu app en una ruta dada", p. ej. montar la API de posts en /api/posts. Consulta URLs y enrutamiento.

Middleware (una "capa" / layer) — código que se ejecuta alrededor de cada petición — antes de tu handler y después de él — para preocupaciones transversales como el registro, el límite de tasa, las cabeceras de seguridad o el CSRF. "Layer" es la palabra de Rustango para una pieza de middleware. Consulta la guía de Middleware.

Pool (o executor) — la conexión a la base de datos que tu código usa para leer y escribir. Rustango te pide pasar el pool explícitamente a cada llamada a la base de datos (en vez de ocultarlo en un global), para que siempre quede claro qué toca la base de datos. Verás &pool como último argumento de las llamadas del ORM.

QuerySet — una consulta a la base de datos que construyes paso a paso en Rust (Post::objects().filter(...).order_by(...)) antes de ejecutarla. Es perezosa (lazy): nada llega a la base de datos hasta que la fetcheas.

Feature flag (bandera de funcionalidad) — un interruptor de encendido/apagado, definido en Cargo.toml, que incluye o excluye una parte del framework en tiempo de compilación. Te permite mantener tu app pequeña compilando solo lo que usas. La mayoría de las features están activadas por defecto.

Andamiaje (Scaffolding) — comandos generadores (startapp, make:serializer, make:viewset…) que escriben archivos iniciales por ti para que no empieces desde una página en blanco. Consulta Andamiaje.

Los datos y la base de datos

Campo / columna (field / column) — un dato de un modelo, como el title o el published_at de un post. "Campo" es el lado Rust; "columna" es el lado de la base de datos; se corresponden uno a uno.

Clave primaria (primary key) — el id único que identifica una fila, normalmente un número autoincremental llamado id.

Clave foránea (foreign key, FK) — un campo de un modelo que apunta a la fila de otro modelo, modelando una relación — p. ej. un Post tiene una clave foránea author_id que apunta a un Author. Es como las filas se referencian entre sí.

NULL / nullable — NULL es la palabra de la base de datos para "sin valor / vacío". Un campo nullable puede estar vacío; uno no-nullable es obligatorio.

Tri-dialecto (tri-dialect) — "funciona igual en las tres bases de datos soportadas" — PostgreSQL, MySQL y SQLite. Cuando una feature es tri-dialecto, puedes cambiar de base de datos sin cambiar tu código.

Multi-tenancy

Detrás de la feature tenancy. Sáltate esta sección si construyes una app corriente de un solo cliente — nada de esto aplica.

Multi-tenancy — ejecutar un único despliegue que sirve a varios clientes, cada uno viendo solo sus propios datos. Rustango resuelve a qué cliente pertenece una petición a partir de su nombre de host y luego la enruta a los datos de ese cliente durante el resto de la petición.

Tenant (u org) — un cliente en un despliegue así. Un tenant tiene un slug (acme), un patrón de host (acme.example.com) y sus propios usuarios. Org es la fila del registro; «tenant» es lo que esa fila describe.

Registro (registry) — la pequeña base de datos que lista los tenants: quiénes son, dónde viven sus datos, si están activos. Distinta de los datos de cualquier tenant, y la única base de datos que el framework siempre necesita.

Modo de almacenamiento (storage mode) — cómo se mantienen separados los datos de un tenant de los de sus vecinos: una base de datos aparte, o un esquema aparte dentro de una compartida. Se elige por tenant al aprovisionar.

Operador (operator) — un administrador del despliegue, no de un tenant. Los operadores crean tenants y enlazan nombres de host; no son usuarios de ningún tenant y viven en el registro. Consulta la consola de operador.

Consola de operador (operator console) — la interfaz web que usan los operadores: aprovisionar tenants, enlazar nombres de host, gestionar otros operadores, leer el rastro de auditoría. Casi cada acción en ella es también un verbo manage, así que puede guionizarse.

Aprovisionamiento (provisioning) — crear un tenant: fabricar su base de datos o esquema, aplicarle las migraciones y registrarlo en el registro.

Unas pocas palabras de Rust

No necesitas saber Rust para leer la mayoría de los ejemplos, pero estas cuatro palabras aparecen por todas partes.

struct — un paquete con nombre de campos, como un registro o una clase que solo tiene datos. Los modelos y los serializers son structs.

Macro derive (#[derive(Model)], #[derive(Serializer)]…) — una anotación de una línea encima de un struct que le dice al compilador que auto-genere un montón de código por ti (el mapeo de la base de datos, la conversión a JSON, …). Es la magia que convierte un simple struct en un modelo o serializer funcional.

async / .await — la forma en que Rust maneja el trabajo que implica esperar (una consulta a la base de datos, una llamada de red). Una función marcada como async es "awaitable"; el .await tras una llamada significa "espera aquí el resultado". Todo lo que toca la base de datos es async.

Result / Option — cómo Rust reporta resultados en lugar de lanzar excepciones. Un Result es "éxito o un error"; una Option es "un valor o nada". El ? que ves tras algunas llamadas significa "si esto falló, detente y devuelve el error".

Frameworks con los que comparamos

Esta documentación dice de vez en cuando "como X" para ayudar a los lectores que vienen de otros ecosistemas. Las comparaciones son un extra — nunca las necesitas para seguir una guía.

Laravel / Rails — frameworks web populares de PHP y Ruby, mencionados por la misma razón de "si has usado esto, esto te resultará familiar".

← Primeros pasos