Home

yrest

Zero-config REST API mock server powered by a YAML file.
Spin up a full REST API in seconds — no code, no database, just a YAML file.

---

Why yrest?

When building a frontend, prototyping an idea, or writing integration tests, you don't want to maintain a real backend. yrest turns a plain YAML file into a fully functional REST API with zero configuration required.

---

Installation

# Run without installing (recommended for quick use)
npx @aggiovato/yrest serve

# Or install globally
npm install -g @aggiovato/yrest
yrest serve

---

Quick start

1. Create a database file

# db.yml
users:
  - id: 1
    name: Alice
    role: admin
  - id: 2
    name: Bob
    role: user

posts:
  - id: 1
    title: Hello world
    userId: 1

2. Start the server

npx @aggiovato/yrest serve db.yml

3. Use your API

curl http://localhost:3070/users
curl http://localhost:3070/users/1
curl http://localhost:3070/posts?_q=hello

That's it. No config files needed unless you want them.

---

Init command

Don't want to write the YAML by hand? Let yrest scaffold it for you:

npx @aggiovato/yrest init
npx @aggiovato/yrest init --sample relational

This creates a db.yml and a yrest.config.yml in the current directory.

---

What you get out of the box

For every collection in your YAML file, yrest exposes:

Method	Route	Description
GET	/collection	List all items
POST	/collection	Create a new item
GET	/collection/:id	Get a single item
PUT	/collection/:id	Fully replace an item
PATCH	/collection/:id	Partially update an item
DELETE	/collection/:id	Delete an item

All write operations persist changes back to the YAML file automatically.

---

Query parameters

Param	Example	Description
?field=value	?role=admin	Exact field filter
?field_like=	?name_like=ali	Case-insensitive substring
?field_gte= / ?field_lte=	?price_gte=10&price_lte=50	Range filter
?field_ne=	?status_ne=inactive	Not equal
?field_start=	?name_start=A	Starts with
?field_regex=	?email_regex=gmail	Regex match
?_q=	?_q=alice	Full-text search across all fields
?_sort= / ?_order=	?_sort=name&_order=desc	Sort
?_page= / ?_limit=	?_page=2&_limit=10	Pagination
?_expand=	?_expand=user	Embed parent object
?_embed=	?_embed=posts	Embed child collection
?_fields=	?_fields=id,name	Project specific fields

---

Modes

Flag	Description
--watch	Reload the YAML file automatically on change
--readonly	Block all write operations (405)
--delay <ms>	Add simulated network latency
--pageable [limit]	Wrap collection responses in { data, pagination }
--snapshot	Save initial state and expose /_snapshot endpoints

---

Meta endpoints

Endpoint	Description
/_about	HTML overview of all routes, query params and examples
/_snapshot	Get snapshot metadata (requires --snapshot)
/_snapshot/save	Save current state as snapshot
/_snapshot/reset	Restore database to last snapshot

---

Configuration file

Instead of passing flags every time, create a yrest.config.yml:

file: db.yml
port: 3070
host: localhost
# base: /api
# watch: false
# readonly: false
# delay: 0
# pageable: false
# snapshot: false

CLI flags always take priority over the config file.

---

Wiki pages

• Configuration — all options and CLI flags in detail
• Query Parameters — filtering, sorting, pagination and relations
• Relations — declaring _rel, using _expand and _embed
• Modes — watch, readonly, delay, pageable, snapshot
• API Reference — full list of generated endpoints