Filter, sort and field selection parameters for list endpoints

What it is

Two widely copied conventions exist. JSON:API (cited) reserves the filter and page query-parameter families, defines sort as a comma-separated list of fields applied in order with a leading minus for descending (sort=-created,title), requires 400 for an unsupported sort, and defines sparse fieldsets: fields[articles]=title,body limits the fields returned per resource type. Google's AIPs define a single filter string with a structured syntax (AIP-160, cited: comparison operators, AND, OR, NOT, functions, field names on the left-hand side) and, for List methods, an order_by string of comma-separated fields with a desc suffix, ascending by default (AIP-132, cited).

Why it matters

Clients that cannot filter or select fields download whole collections and filter locally; that is a common origin of oversized responses and of requests for one-off special endpoints. Conventions that hold across the whole API let a client library implement them once.

How to apply

• Filtering: start with per-field equality parameters (?status=open&owner=42) when the filterable fields are few and fixed; move to a filter expression string when filters combine or change often. Either way, list the filterable fields and operators and reject unknown ones with 400 rather than ignoring them.
• Sorting: accept a list of fields with a direction marker; append a unique tiebreaker (the primary key) server-side so pagination is stable; document the default order.
• Field selection: accept a list of top-level field names; return the full representation when the parameter is absent; treat unknown fields as errors. Prefer a few named views (basic, full) when only a few combinations make sense.
• Index whatever you allow to be filtered or sorted; an exposed sort on an unindexed column is a self-service full table scan.
• Include filter, sort and fields in cache keys and in cursor tokens so page two uses the same query as page one.

Pitfalls

AIP-132 notes that ordering can always be added later but removing it is a breaking change; the same holds for filters and selectable fields, and for the default field set, so expose only what you can keep. Filter parsing that reaches the database as string concatenation is injection; map parsed field names to columns explicitly. In AIP-160, OR binds tighter than AND, unlike most programming languages, so documentation should show parentheses.