Filtering

Filtering trims a normalized Restish response before formatting. Use shorthand for direct paths and projections; use jq for richer transforms.

Filter Roots

• proto for the response protocol string
• status for the numeric HTTP status
• headers for response headers
• links for normalized hypermedia links
• body for decoded response body

restish api.rest.sh/images -f links.next
restish api.rest.sh/example -f body.basics.profiles

Shorthand Paths

restish api.rest.sh/images --rsh-collect -f body[0].name
restish api.rest.sh/images --rsh-collect -f body[-1].self
restish api.rest.sh/example -f body.volunteer[0].organization

Selection And Projection

restish api.rest.sh/example -f 'body.basics.{name, url, profiles}'
restish api.rest.sh/images --rsh-no-paginate -f '{next: links.next, first: body[0].self}'
restish api.rest.sh/example -f 'body..url'

Recursive search (..) walks every matching field below the current path. Recursive search and projection are useful when exploring unfamiliar API responses.

jq Filters

jq filters use jq’s current-input root, operators, functions, and pipeline syntax:

restish api.rest.sh/images --rsh-collect -f '.body | map(.format) | unique'
restish api.rest.sh/images --rsh-no-paginate -f '{next: .links.next, first: .body[0].self}'
restish api.rest.sh/example -f '.. | .url?'

Force a language when a filter is ambiguous:

restish api.rest.sh/images --rsh-filter-lang shorthand -f '{next: links.next}'
restish api.rest.sh/images --rsh-filter-lang jq -f '{next: .links.next}'

In the default auto mode, Restish tries both shorthand and jq. Bare normalized-response roots such as links.next mean shorthand. A leading jq current-input field such as .links.next or .body[0].self means jq, even when shorthand would also accept the expression. Recursive descent stays distinct: ..url is shorthand, while .. | .url? is jq. When both languages fail, Restish reports the likely parser first and still includes the other parser’s error.

Pagination And Collecting

Default pagination filters each item as it arrives. The item is still wrapped under the normalized body root, so item fields are selected as body.name, body.self, and similar filters. This stays true when stdout is redirected or when you choose a document format such as -o json; document formats collect the filtered item results into one valid document. Use --rsh-collect when the filter needs the whole collection:

Scalar Lines

Explicit scalar filters print without JSON string quotes. Use -o lines when the filtered value is an array or stream of scalars and you want one value per line. -o lines rejects structured objects; use -o json when you need to preserve array or object shape.

Related Pages

• Query Syntax
• Output
• Pagination