Filtering and Sorting

Asking for a subset

Most list endpoints return everything by default, but you rarely actually want everything. Filtering lets you attach conditions to the request so the server sends back only the records that match, which saves bandwidth, memory, and processing time on both ends of the connection.

Filters live in the query string — the part of the URL that follows the ?. A typical request narrows a collection down to a particular status, a date range, or a specific owner, and the server applies those conditions before it paginates the result. Filtering on the server rather than in your own code is almost always the right choice: it transfers far less data and lets the API lean on its indexes to answer quickly instead of streaming you rows you will only throw away.

How filters look

Conventions vary quite a bit between APIs, so always check the documentation, but a few patterns recur often enough to recognise on sight. Simple equality reads naturally as a parameter, and ranges are commonly expressed with suffixed operators on the field name:

GET /v1/cases?status=open&created_after=2026-01-01

Some APIs use bracketed operators such as amount[gte]=1000, others use dotted paths or comma-separated value lists. The key is internal consistency: learn the particular style this API uses and then apply it the same way everywhere, rather than mixing conventions you have picked up from other services. Guessing a syntax the endpoint does not support usually just gets the filter silently ignored.

Sorting results

Sorting controls the order in which records come back. A common convention is a sort parameter naming a field, with a leading minus sign or an explicit direction keyword to choose ascending or descending order — for example sort=-created_at to put the newest records first.

Pair sorting thoughtfully with pagination, because a stable, well-defined order is precisely what lets paging return consistent, non-overlapping pages. Sorting on a field whose values can tie, or that changes while you scan, can reshuffle results between pages and reintroduce the very duplicates and gaps pagination was meant to prevent. Prefer ordering on something unique and stable, such as a creation timestamp combined with an identifier, when you intend to walk the whole collection.

Encoding and good habits

Values in a query string must be URL-encoded. Spaces, ampersands, plus signs, slashes, and other reserved characters all need escaping, and most HTTP libraries will do this correctly for you if you pass parameters as structured data rather than concatenating the string by hand. Hand-built query strings are a frequent and avoidable source of escaping bugs that only surface on certain inputs.

Filtering and sorting work hand in hand with pagination to keep payloads small and predictable: narrow with filters, order with sort, then walk the result page by page. Together these three controls let you pull exactly the slice of data you need and nothing more.