Query parameters

All query parameters that control yrest behaviour are prefixed with _. Field filters use the field name directly (with optional operator suffixes).

---

Field filters

Filter items by exact field value. Multiple filters are ANDed — all conditions must match.

GET /users?role=admin
GET /users?role=admin&active=true

Repeated params on the same field are treated as OR — any match passes:

GET /users?role=admin&role=user   # role is admin OR user

---

Field operators

Append an operator suffix to the field name to use advanced comparisons.

field_gte — greater than or equal

GET /products?price_gte=100

Numeric comparison when both sides are numbers; lexicographic otherwise.

field_lte — less than or equal

GET /products?price_lte=500
GET /products?price_gte=100&price_lte=500   # range

field_ne — not equal

GET /users?status_ne=inactive

field_like — case-insensitive substring

GET /users?name_like=ali      # matches Alice, Alicia, …

field_start — case-insensitive prefix

GET /users?name_start=A       # matches Alice, Ana, Avocado, …

field_regex — regular expression

GET /users?email_regex=gmail
GET /users?email_regex=^alice

Case-insensitive by default. Invalid patterns return no results without crashing.

---

Full-text search — ?_q

Searches the term across all scalar fields of each item (case-insensitive substring). Object and array values are skipped. An item passes if any field matches.

GET /users?_q=alice
GET /users?_q=example.com

?_q can be combined with field filters and operators:

GET /users?_q=example&role=admin

---

Sorting — ?_sort and ?_order

GET /users?_sort=name
GET /users?_sort=name&_order=desc
GET /products?_sort=price&_order=asc

Param	Values	Default
_sort	Any field name	(no sort)
_order	asc | desc	asc

Numbers are compared numerically; strings are compared case-insensitively. Items missing the sort field are pushed to the end.

---

Pagination — ?_page and ?_limit

Standard mode

GET /users?_page=2&_limit=10

Returns the requested slice. The X-Total-Count response header contains the total number of items before pagination.

Pageable mode

When the server runs with --pageable, the response is wrapped in an envelope:

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

?_limit overrides the server default per request:

GET /users?_page=1&_limit=5

---

Expand parent — ?_expand

Embeds a related parent object into each child item. Requires a _rel declaration in the YAML file.

GET /posts?_expand=user
GET /posts/1?_expand=user

Multiple expansions — comma-separated or repeated:

GET /posts?_expand=user,category
GET /posts?_expand=user&_expand=category

The parent object is embedded under the relation key (e.g. user). The original foreign key field (e.g. userId) is preserved.

See Relations for how to declare _rel.

---

Embed children — ?_embed

Embeds a related child collection into each parent item. The inverse of ?_expand. Requires a _rel declaration.

GET /users?_embed=posts
GET /users/1?_embed=posts

Multiple embeds:

GET /users?_embed=posts,comments
GET /users?_embed=posts&_embed=comments

Each parent item gets a key with an array of its matching children. Items with no children receive an empty array.

See Relations for how to declare _rel.

---

Field projection — ?_fields

Returns only the specified fields. Applied last in the pipeline, so it can project fields added by ?_expand or ?_embed.

GET /users?_fields=id,name
GET /users/1?_fields=id,name,email
GET /posts?_expand=user&_fields=id,title,user
GET /users?_embed=posts&_fields=id,posts

Fields not present in the item are silently ignored.

---

Pipeline order

When multiple params are combined, yrest applies them in this order:

1. filterByQuery    (field filters + operators)
2. fullTextSearch   (?_q)
3. sortBy           (?_sort, ?_order)
4. paginate         (?_page, ?_limit)
5. expandItems      (?_expand)
6. embedItems       (?_embed)
7. projectFields    (?_fields)

This means ?_fields can include keys added by ?_expand or ?_embed, and ?_q runs on the original fields before expansion.