Quick Start

Getting a full mock REST API running with yRest takes under a minute. All you need is a YAML file — no server code, no configuration, no database to set up. The four steps below take you from zero to a live API you can call from your frontend.

What this guide covers

This walkthrough shows yRest in standalone mock mode — you run it with npx, point it at a YAML file, and immediately get a REST API. No installation, no backend code.

If you want to embed yRest inside a test suite (Vitest, Playwright, Cypress), see Programmatic API instead.

1. Create your database file

The init command scaffolds a ready-to-use db.yml and a yrest.config.yml in the current directory:

npx @yrest/cli init

Three built-in templates are available via --sample:

Template	What it contains
basic(default)	users and posts collections — good for a first look
relational	users, posts, comments with _rel links between them
ecommerce	products, orders, customers with richer field schemas

npx @yrest/cli init --sample relational   # relational template
npx @yrest/cli init --sample ecommerce    # e-commerce template
npx @yrest/cli init --file api.yml        # custom output filename

You can also skip init entirely and write the file by hand — the format is just 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

Any top-level key that doesn’t start with _ becomes a collection with full CRUD routes.

2. Start the server

With your db.yml ready, start the server with a single command. yRest reads the file, registers a full CRUD route for every collection, and begins listening — no compilation step, no database setup, no config file required.

npx @yrest/cli serve db.yml

yrest  ·  http://localhost:3070

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

Meta:
  GET  /_about

The default port is 3070. It was chosen to avoid conflicts with the most common development ports (3000, 3001, 4000, 8080, 8000) while staying in a familiar range, so you can run yRest alongside your real frontend dev server without touching any config.

Available flags:

Flag	Default	Description
-p, —port <n>	3070	Port to listen on
-H, —host <host>	localhost	Host to bind (use 0.0.0.0 to expose on LAN)
-b, —base <path>	(none)	Prefix all routes — e.g. —base /api/v1
-w, —watch	off	Reload db.yml automatically when it changes
-r, —readonly	off	Reject all writes (POST/PUT/PATCH/DELETE → 405)
-d, —delay <ms>	0	Add a fixed latency to every response
—pageable [limit]	off	Wrap list responses in { data, pagination }
—snapshot	off	Expose POST /_snapshot to save live state back to disk
—handlers <file>	(none)	Path to a yrest.handlers.js file with custom logic
—id-strategy <s>	increment	increment (1, 2, 3…) or uuid

Options can also be set in yrest.config.yml so you don’t need to repeat them on every run. CLI flags always take priority over the config file.

3. Use the API

Every collection gets the full REST surface automatically. Here are the most common operations against the users collection from the example above:

# List all users
curl http://localhost:3070/users

# Get a single user by id
curl http://localhost:3070/users/1

# Filter by field value
curl "http://localhost:3070/users?name_like=ana"

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

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

# Create a new user (id is assigned automatically)
curl -X POST http://localhost:3070/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Carlos","email":"carlos@test.com"}'

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

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

Changes made via POST/PUT/PATCH/DELETE are persisted back to db.yml in real time. Restart the server to reset to the original data, or enable --snapshot and call POST /_snapshot to save the current state explicitly.

4. Explore the API overview

Open http://localhost:3070/_about in your browser.

This built-in page shows every generated endpoint grouped by collection, the active server modes, any custom routes defined in _routes, and ready-to-run curl examples for each operation. It updates automatically when the server reloads — useful as a quick reference while you build your frontend.

Next steps

• Configuration — all yrest.config.yml options
• Database format — learn the full YAML schema
• Query parameters — filters, sorting, pagination, projections
• Relations — link collections with _rel
• Custom routes — add non-CRUD endpoints
• Programmatic API — use in Vitest and Playwright