# Query parameter naming is consistent

- **Pattern:** `ab-000355` (`api-design.naming-conventions.query-param-naming`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000355
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000355)

## Why it matters

When one list endpoint paginates with `page`/`limit` and another with `offset`/`count`, every consumer building a generic list component must branch on the endpoint. Sorting inconsistency — `sort` on one, `orderBy` on another — means documentation is never sufficient; developers must check each endpoint individually. This is a direct iso-25010:2011 maintainability.modifiability failure: the API surface area effectively doubles for consumers who need to handle multiple list endpoints.

## Severity rationale

Medium because inconsistent query parameter naming imposes per-endpoint special-casing on every client without enabling security vulnerabilities.

## Remediation

Define a standard set of query parameter names once and apply them everywhere. Create a shared query parameter parser that all list endpoints import:

```
// Standard pagination (pick one set, never both):
?page=1&limit=20

// Standard sorting:
?sort=created_at&order=desc

// Standard filtering:
?status=ACTIVE&type=PREMIUM

// Standard search:
?q=search+term
```

Document these names in your API reference and enforce them with a shared middleware or parser module so new endpoints cannot diverge.

## Detection

- **ID:** `query-param-naming`
- **Severity:** `medium`
- **What to look for:** Examine query parameters used across list/search endpoints. Check for consistent naming of common patterns: pagination (`page`/`limit` vs `offset`/`count` vs `cursor`/`pageSize`), sorting (`sort`/`order` vs `sortBy`/`orderBy` vs `sort_field`/`sort_dir`), filtering (`filter[field]` vs `field=value` vs `q`), and field selection (`fields` vs `select` vs `include`). The convention itself matters less than consistency -- every list endpoint should use the same parameter names for the same concepts.
- **Pass criteria:** Count all list endpoints and list all query parameter names used across them. All list endpoints use the same parameter names for pagination, sorting, and filtering. One naming convention for query params (camelCase, snake_case, or bracket notation) applied consistently.
- **Fail criteria:** Different list endpoints use different parameter names for the same concept (e.g., one uses `page`/`limit`, another uses `offset`/`count`). Or query param casing is inconsistent (`sortBy` on one endpoint, `sort_by` on another).
- **Skip (N/A) when:** Fewer than 2 list endpoints exist, or no endpoints accept query parameters.
- **Detail on fail:** Note the specific inconsistencies (e.g., "`/api/users` uses `?page=1&limit=20` but `/api/orders` uses `?offset=0&count=20`. Sorting: `/api/users` has `?sort=name` but `/api/posts` has `?orderBy=title`."). Max 500 chars.
- **Remediation:** Define a standard set of query parameter names and use them everywhere:

  ```
  // Standard pagination:
  ?page=1&limit=20

  // Standard sorting:
  ?sort=created_at&order=desc

  // Standard filtering:
  ?status=active&type=premium

  // Standard search:
  ?q=search+term
  ```

  Document these conventions and create a shared query parameter parser that all list endpoints use.

## External references

- iso-25010 maintainability.modifiability

Taxons: code-quality

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