Inicio rápido

Qué cubre esta guía

Este tutorial muestra yRest en modo mock independiente — lo ejecutas con npx, apuntas a un archivo YAML y obtienes de inmediato una REST API. Sin instalación, sin código backend.

Si deseas integrar yRest en un conjunto de pruebas (Vitest, Playwright, Cypress), consulta la API programática.

1. Crea tu archivo de base de datos

El comando init genera un db.yml listo para usar y un yrest.config.yml en el directorio actual:

npx @yrest/cli init

Hay tres plantillas disponibles con --sample:

Plantilla	Contenido
basic(por defecto)	Colecciones users y posts — ideal para un primer vistazo
relational	users, posts, comments con enlaces _rel entre ellos
ecommerce	products, orders, customers con esquemas de campos más ricos

npx @yrest/cli init --sample relational   # plantilla relacional
npx @yrest/cli init --sample ecommerce    # plantilla e-commerce
npx @yrest/cli init --file api.yml        # nombre de archivo personalizado

También puedes omitir init y escribir el archivo manualmente — el formato es simplemente YAML:

db.yml

users:
  - id: 1
    name: Ana
    email: ana@test.com
  - id: 2
    name: Luis
    email: luis@test.com

posts:
  - id: 1
    title: First post
    userId: 1

Cualquier clave de nivel superior que no comience con _ se convierte en una colección con rutas CRUD completas.

2. Inicia el servidor

npx @yrest/cli serve db.yml

yrest  ·  http://localhost:3070

Collections (base: /):
  CRUD  /users
  CRUD  /posts

Meta:
  GET  /_about

El puerto por defecto es 3070. Se eligió para evitar conflictos con los puertos de desarrollo más comunes (3000, 3001, 4000, 8080, 8000), de modo que puedes ejecutar yRest junto a tu servidor de desarrollo frontend sin tocar ninguna configuración.

Opciones disponibles:

Flag	Por defecto	Descripción
-p, —port <n>	3070	Puerto en el que escuchar
-H, —host <host>	localhost	Host a vincular (usa 0.0.0.0 para exponer en LAN)
-b, —base <path>	(ninguno)	Prefijo para todas las rutas — ej. —base /api/v1
-w, —watch	off	Recarga db.yml automáticamente al detectar cambios
-r, —readonly	off	Rechaza todas las escrituras (POST/PUT/PATCH/DELETE → 405)
-d, —delay <ms>	0	Añade una latencia fija a cada respuesta
—pageable [limit]	off	Envuelve las listas en { data, pagination }
—snapshot	off	Expone POST /_snapshot para guardar el estado en disco
—handlers <file>	(ninguno)	Ruta a un archivo yrest.handlers.js con lógica personalizada
—id-strategy <s>	increment	increment (1, 2, 3…) o uuid

Las opciones también se pueden establecer en yrest.config.yml para no tener que repetirlas en cada ejecución. Los flags de CLI siempre tienen prioridad sobre el archivo de configuración.

3. Usa la API

Cada colección obtiene la superficie REST completa automáticamente. Aquí están las operaciones más comunes sobre la colección users del ejemplo anterior:

# Listar todos los usuarios
curl http://localhost:3070/users

# Obtener un usuario por id
curl http://localhost:3070/users/1

# Filtrar por valor de campo
curl "http://localhost:3070/users?name_like=ana"

# Paginar
curl "http://localhost:3070/users?_page=1&_limit=10"

# Ordenar
curl "http://localhost:3070/users?_sort=name&_order=asc"

# Crear un nuevo usuario (el id se asigna automáticamente)
curl -X POST http://localhost:3070/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Carlos","email":"carlos@test.com"}'

# Actualización parcial
curl -X PATCH http://localhost:3070/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana Actualizada"}'

# Eliminar
curl -X DELETE http://localhost:3070/users/1

Los cambios realizados mediante POST/PUT/PATCH/DELETE se persisten en db.yml en tiempo real. Reinicia el servidor para volver a los datos originales, o activa --snapshot y llama a POST /_snapshot para guardar el estado actual explícitamente.

4. Explora el resumen de la API

Abre http://localhost:3070/_about en tu navegador.

Esta página integrada muestra todos los endpoints generados agrupados por colección, los modos de servidor activos, las rutas personalizadas definidas en _routes y ejemplos curl listos para ejecutar para cada operación. Se actualiza automáticamente cuando el servidor se recarga — útil como referencia rápida mientras construyes tu frontend.

Próximos pasos

• Configuración — todas las opciones de yrest.config.yml
• Formato de base de datos — aprende el esquema YAML completo
• Parámetros de consulta — filtros, ordenación, paginación, proyecciones
• Relaciones — vincula colecciones con _rel
• Rutas personalizadas — añade endpoints que no son CRUD
• API programática — úsalo en Vitest y Playwright