Avvio rapido

1. Crea il tuo file di database

Il comando init genera un db.yml pronto all’uso e un yrest.config.yml nella directory corrente:

npx @yrest/cli init

Sono disponibili tre template tramite --sample:

Template	Contenuto
`basic`(predefinito)	Collection `users` e `posts` — ideale per una prima occhiata
`relational`	`users`, `posts`, `comments` con link `_rel` tra loro
`ecommerce`	`products`, `orders`, `customers` con schemi di campo più ricchi

npx @yrest/cli init --sample relational   # template relazionale
npx @yrest/cli init --sample ecommerce    # template e-commerce
npx @yrest/cli init --file api.yml        # nome file personalizzato

Puoi anche saltare init e scrivere il file manualmente — il formato è semplice YAML:

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

Qualsiasi chiave di primo livello che non inizia con _ diventa una collection con route CRUD complete.

2. Avvia il server

npx @yrest/cli serve db.yml

yrest  ·  http://localhost:3070

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

Meta:
  GET  /_about

La porta predefinita è 3070. È stata scelta per evitare conflitti con le porte di sviluppo più comuni (3000, 3001, 4000, 8080, 8000), così puoi eseguire yRest insieme al tuo server di sviluppo frontend senza toccare alcuna configurazione.

Opzioni disponibili:

Flag	Predefinito	Descrizione
`-p, —port <n>`	`3070`	Porta su cui ascoltare
`-H, —host <host>`	`localhost`	Host a cui collegarsi (usa `0.0.0.0` per esporre sulla LAN)
`-b, —base <path>`	(nessuno)	Prefissa tutte le route — es. `—base /api/v1`
`-w, —watch`	off	Ricarica `db.yml` automaticamente quando cambia
`-r, —readonly`	off	Rifiuta tutte le scritture (POST/PUT/PATCH/DELETE → 405)
`-d, —delay <ms>`	`0`	Aggiunge una latenza fissa a ogni risposta
`—pageable [limit]`	off	Avvolge le liste in `{ data, pagination }`
`—snapshot`	off	Espone `POST /_snapshot` per salvare lo stato corrente su disco
`—handlers <file>`	(nessuno)	Percorso a un file `yrest.handlers.js` con logica personalizzata
`—id-strategy <s>`	`increment`	`increment` (1, 2, 3…) o `uuid`

Le opzioni possono anche essere impostate in yrest.config.yml così non devi ripeterle ad ogni avvio. I flag CLI hanno sempre la precedenza sul file di configurazione.

3. Usa l’API

Ogni collection ottiene automaticamente la superficie REST completa. Ecco le operazioni più comuni sulla collection users dell’esempio sopra:

# Elencare tutti gli utenti
curl http://localhost:3070/users

# Ottenere un utente per id
curl http://localhost:3070/users/1

# Filtrare per valore di campo
curl "http://localhost:3070/users?name_like=ana"

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

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

# Creare un nuovo utente (l'id viene assegnato automaticamente)
curl -X POST http://localhost:3070/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Carlos","email":"carlos@test.com"}'

# Aggiornamento parziale
curl -X PATCH http://localhost:3070/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana Aggiornata"}'

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

Le modifiche effettuate tramite POST/PUT/PATCH/DELETE vengono salvate in db.yml in tempo reale. Riavvia il server per tornare ai dati originali, oppure abilita --snapshot e chiama POST /_snapshot per salvare lo stato corrente esplicitamente.

4. Esplora il riepilogo dell’API

Apri http://localhost:3070/_about nel tuo browser.

Questa pagina integrata mostra tutti gli endpoint generati raggruppati per collection, le modalità server attive, le route personalizzate definite in _routes ed esempi curl pronti all’uso per ogni operazione. Si aggiorna automaticamente quando il server si ricarica — utile come riferimento rapido mentre costruisci il tuo frontend.

Prossimi passi

Configurazione — tutte le opzioni di yrest.config.yml
Formato database — impara lo schema YAML completo
Parametri di query — filtri, ordinamento, paginazione, proiezioni
Relazioni — collega le collection con _rel
Route personalizzate — aggiungi endpoint non-CRUD
API programmatica — usa con Vitest e Playwright