Modes

Modes

Modes modify the server's behaviour globally. They can be set via CLI flags or in yrest.config.yml. Active modes are displayed as badges on /_about.

---

Watch mode — --watch

Reloads the YAML file automatically when it changes on disk.

yrest serve --watch
yrest serve db.yml -w

# yrest.config.yml
watch: true

How it works:

• yrest watches the database file with a 300 ms poll interval
• Changes are debounced with a 100 ms delay to avoid partial reads
• Only changes within existing collections are reflected immediately
• Adding or removing entire top-level collections requires a server restart
• If the file contains a YAML syntax error, the reload is skipped and the error is printed to the console — the previous state is preserved

Console output:

[watch] reloaded db.yml
[watch] failed to reload db.yml — <yaml error message>

---

Readonly mode — --readonly

Rejects all mutating requests with 405 Method Not Allowed.

yrest serve --readonly
yrest serve db.yml -r

# yrest.config.yml
readonly: true

Affected methods: POST, PUT, PATCH, DELETE.
GET, HEAD and OPTIONS are always allowed.

Response:

{
  "error": "Server is running in readonly mode"
}

Useful when sharing a mock API with a team and you want to prevent accidental data modification.

---

Delay mode — --delay

Adds a fixed delay (in milliseconds) to every response.

yrest serve --delay 500
yrest serve db.yml -d 300

# yrest.config.yml
delay: 300

Simulates real-world network latency, allowing you to test loading states, skeleton screens and timeout handling in your frontend.

The delay is applied uniformly to all responses including errors.

---

Pageable mode — --pageable

Wraps GET collection responses in a { data, pagination } envelope.

yrest serve --pageable           # default limit: 10
yrest serve --pageable 25        # custom default limit

# yrest.config.yml
pageable: true    # limit: 10
pageable: 25      # limit: 25

Response shape:

{
  "data": [ … ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 47,
    "totalPages": 5,
    "isFirst": true,
    "isLast": false,
    "hasNext": true,
    "hasPrev": false
  }
}

Navigating pages:

GET /users?_page=2
GET /users?_page=2&_limit=5    # override limit per request

When pageable mode is active, the X-Total-Count header is not set — all pagination metadata is in the response body instead.

Without --pageable, pagination is opt-in via ?_page / ?_limit and the total count is returned in the X-Total-Count header.

---

Snapshot mode — --snapshot

Saves a deep copy of the database state at startup and exposes three endpoints that let you save and restore the database programmatically.

yrest serve --snapshot

# yrest.config.yml
snapshot: true

Endpoints:

GET /_snapshot

Returns metadata about the current snapshot.

{
  "savedAt": "2026-06-08T00:00:00.000Z",
  "collections": {
    "users": 3,
    "posts": 5
  }
}

POST /_snapshot/save

Replaces the stored snapshot with the current database state.

curl -X POST http://localhost:3070/_snapshot/save

POST /_snapshot/reset

Restores the database to the last saved snapshot and persists to disk.

curl -X POST http://localhost:3070/_snapshot/reset

Typical workflow in tests:

# Before test suite: server starts → snapshot saved automatically at startup

# Run tests that mutate data…

# After each test: reset to clean state
curl -X POST http://localhost:3070/_snapshot/reset

This eliminates the need to restart the server between test runs.

---

Combining modes

All modes can be combined freely:

yrest serve --watch --snapshot --delay 200 --pageable 20

# yrest.config.yml
watch: true
snapshot: true
delay: 200
pageable: 20