# Sort/filter fields documented

- **Pattern:** `ab-000371` (`api-design.developer-ergonomics.sort-filter-docs`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000371
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000371)

## Why it matters

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.

## Severity rationale

Medium because undocumented sort/filter fields force consumers into trial-and-error integration and silent failures when invalid values are ignored without error.

## Remediation

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

```yaml
# 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"
```

```ts
// 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.

## Detection

- **ID:** `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:

  ```yaml
  # 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"
  ```

  ```ts
  // 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)
  }
  ```

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000371