API reference

yrest generates REST endpoints automatically from the collections in your YAML file. This page documents every route type, its behaviour and its response shape.

---

Resource routes

For each top-level collection in the YAML file (excluding _rel), yrest registers six routes under {base}/{collection}.

---

GET /{collection}

Returns all items in the collection.

Query params: all Query Parameters are supported.

Response: 200 OK — array of items (or { data, pagination } in pageable mode).

GET /users
GET /users?role=admin&_sort=name&_limit=10
GET /users?_q=alice&_fields=id,name

Headers (standard mode only):

Header	Description
X-Total-Count	Total items before pagination (only when ?_page or ?_limit is used)

---

POST /{collection}

Creates a new item and persists it to the YAML file.

Body: JSON object (Content-Type: application/json required).

Response: 201 Created — the created item including its assigned id.

If the body includes an id it is used as-is; otherwise an incremental integer id is automatically assigned.

curl -X POST http://localhost:3070/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Charlie", "role": "user"}'

{ "id": 3, "name": "Charlie", "role": "user" }

Errors:

Status	Condition
400	Body is not a JSON object (array, null, malformed)
415	Missing Content-Type: application/json header
405	Server is in readonly mode

---

GET /{collection}/:id

Returns a single item by id.

Query params: ?_expand, ?_embed, ?_fields are supported.

Response: 200 OK — the item object.

GET /users/1
GET /users/1?_expand=role&_fields=id,name

Errors:

Status	Condition
404	No item with the given id

---

PUT /{collection}/:id

Fully replaces an item. All fields are replaced with the body content. The original id is always preserved regardless of what the body contains.

Body: JSON object (Content-Type: application/json required).

Response: 200 OK — the replaced item.

curl -X PUT http://localhost:3070/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated", "role": "admin"}'

Errors:

Status	Condition
400	Body is not a JSON object
404	No item with the given id
405	Server is in readonly mode

---

PATCH /{collection}/:id

Partially updates an item. Only the fields present in the body are changed; all other fields are left unchanged.

Body: JSON object (Content-Type: application/json required).

Response: 200 OK — the updated item.

curl -X PATCH http://localhost:3070/users/1 \
  -H "Content-Type: application/json" \
  -d '{"role": "superadmin"}'

Errors:

Status	Condition
400	Body is not a JSON object
404	No item with the given id
405	Server is in readonly mode

---

DELETE /{collection}/:id

Removes an item from the collection and persists the change to the YAML file.

Response: 200 OK — the deleted item (returned as confirmation).

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

Errors:

Status	Condition
404	No item with the given id
405	Server is in readonly mode

---

Nested routes

For each relation declared in _rel, yrest registers two additional routes. See Relations for how to declare relations.

---

GET /{parent}/:id/{child}

Returns all child items whose foreign key matches the parent id.

GET /users/1/posts

Response: 200 OK — array of child items (filtered by FK).

Errors:

Status	Condition
404	Parent item does not exist

---

GET /{parent}/:id/{child}/:childId

Returns a single child item scoped to the given parent.

GET /users/1/posts/2

Response: 200 OK — the child item.

Errors:

Status	Condition
404	Parent does not exist, child does not exist, or child does not belong to this parent

---

Meta endpoints

Meta endpoints are always mounted at the root regardless of the --base setting.

---

GET /_about

Returns an HTML page with a live overview of the running server: all routes, active modes, query parameter reference and curl examples.

curl http://localhost:3070/_about
# or open in browser

---

GET /_snapshot

Returns metadata about the current snapshot. Requires --snapshot mode.

curl http://localhost:3070/_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. Requires --snapshot mode.

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

---

POST /_snapshot/reset

Restores the database to the last saved snapshot and persists to disk. Requires --snapshot mode.

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

---

Error responses

All errors follow the same shape:

{ "error": "Human-readable message" }

Status	Meaning
400	Bad request — malformed or invalid body
404	Resource not found
405	Method not allowed — readonly mode active
415	Unsupported media type — missing Content-Type header
500	Internal server error