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.

• ID: api-design.developer-ergonomics.sort-filter-docs

• Severity: medium

• What to look for: For list endpoints that support sorting and filtering, check whether the available sort fields and filter fields are documented. Look for: documentation in the OpenAPI spec (parameter descriptions, enum of allowed values), README API section listing filter options, or inline code comments. Check whether consumers can discover valid sort/filter values without trial and error. Also check: what happens when an invalid sort/filter value is provided -- does the API return a helpful error message listing valid options, or silently ignore the parameter?

• Pass criteria: Count the sort/filter fields available across all list endpoints. Available sort fields and filter fields are documented somewhere (OpenAPI spec, API docs, README). Invalid sort/filter values return an error message that lists at least 1 valid option.

• Fail criteria: Sort/filter fields are not documented anywhere. Consumers must guess valid values or read source code. Invalid values are silently ignored with no feedback.

• Skip (N/A) when: No endpoints support sorting or filtering.

• Detail on fail: Note what's missing (e.g., "GET /api/users accepts ?sort= parameter but valid values (name, created_at, email) are not documented. Invalid sort values like ?sort=foo return results sorted by id with no error or warning."). Max 500 chars.

• Remediation: Document available sort/filter fields and validate inputs:

  # OpenAPI -- document sort options:
  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:
  const VALID_SORT_FIELDS = ['created_at', 'name', 'email'] as const
  const sort = searchParams.get('sort') ?? 'created_at'
  if (!VALID_SORT_FIELDS.includes(sort)) {
    return apiError('INVALID_SORT', `Valid sort fields: ${VALID_SORT_FIELDS.join(', ')}`, 400)
  }