Sort/filter fields documented

When sort and filter fields are undocumented, consumers discover valid values by trial and error or by reading the source. When invalid values are silently ignored — returning results in an unspecified order — consumers write broken code that appears to work until a data change reveals the sort was never applied. iso-25010:2011 maintainability.analysability is the direct impact: the API cannot be understood from its own interface and requires source code access to use correctly.

Document available sort and filter fields in your OpenAPI spec and validate inputs with an explicit error listing valid options:

# OpenAPI -- document allowed sort values:
parameters:
  - name: sort
    in: query
    schema:
      type: string
      enum: [created_at, name, email, updated_at]
    description: "Field to sort by. Default: created_at"

// Validate and error on invalid sort with guidance:
const VALID_SORT_FIELDS = ['created_at', 'name', 'email'] as const
const sort = searchParams.get('sort') ?? 'created_at'
if (!VALID_SORT_FIELDS.includes(sort as typeof VALID_SORT_FIELDS[number])) {
  return apiError('INVALID_SORT', `Valid sort fields: ${VALID_SORT_FIELDS.join(', ')}`, 400)
}

The error message must list at least one valid option — telling consumers only that the value is invalid without saying what is valid is not useful.