Skip to content
API Design Learn/Querying, Errors & Contracts
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Filtering, Sorting & Search Query Params

4 min read

You'll learn to

  • -Put filtering, sorting and search in query parameters, and keep the path for identifying the resource
  • -Choose one consistent convention for each: field=value, a sort prefix, and a single q for search
  • -Keep every parameter optional, so a client that never sends it keeps working

Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.

A collection endpoint like /orders rarely stays a plain "return everything" endpoint. Clients need to filter by status, sort by date and search by keyword. A query parameter is the part of a URL after the ?, written as name=value and joined with &. This is where that flexibility belongs, kept apart from the path so the resource's identity (/orders) stays stable while the options around it grow.

An Analogy: The Shop Door and the Shelf Labels

A shop keeps the same address and the same front door, however many ways you can browse inside. Filters, sorting and search are like the signs on the shelves and the box at the counter. They narrow what you see, and a shopper who ignores them still gets the normal shop. Query parameters should work the same way.

Filtering, sorting, and search as query parameters
GET /orders?status=shipped&sort=-created_at&q=laptop

# status=shipped        filter to orders with this status
# sort=-created_at       sort by created_at descending (- prefix = descending)
# q=laptop               free-text search across searchable fields

Consistent Conventions Matter More Than Any Single Choice

  • -Filtering: field=value for an exact match is the simplest default. For ranges and multiple values, document the convention, such as price_min and price_max, or status=shipped,delivered for "either".
  • -Sorting: a sort parameter with a field name, using a prefix such as - for descending, or a separate order parameter. Either works, so long as you pick one and use it everywhere.
  • -Search: a single q parameter for free-text search is a widely recognized convention, better than inventing a different name for each endpoint.

The demo implements those conventions against four sample orders. Read the five requests and the order in which the ids come back. The first request sends nothing, and still works.

Press Run: the same endpoint answers every combination, and works with none

So "orders over $100, newest first" is simply GET /orders?price_min=100&sort=-created_at, with no new endpoint.

Query Parameters Must Stay Additive

The most important property: adding a new parameter must never break a client that does not send it. A client written before sort existed keeps working exactly as before once sort is added, because leaving out an optional parameter always falls back to a sensible default, such as the creation order.

A quick check for any new parameter: "if a client never sends this, does the endpoint still behave sensibly?" If the client must know about it to avoid broken behavior, it should not be a query parameter. Treat it as part of a versioned change instead.

Interview Signal

The interviewer asks how you'd support "orders over $100, sorted by newest first" on GET /orders.

Weak Answer

"I'd add a new endpoint like /orders/expensive-sorted that returns exactly that."

Strong Answer

"I'd use query parameters on the existing collection endpoint: GET /orders?price_min=100&sort=-created_at. That composes with any other filter a client might already be using, rather than creating a new endpoint for every specific combination of filters someone might want - which would grow unboundedly as more combinations come up."

Check Yourself1 / 5

Why do filtering and sorting belong in query parameters rather than the resource path?

Ready to Build This?

Design The Query Master in the API Design Lab's REST Foundations act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!