Query parameter naming is consistent

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.

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.

• ID: api-design.naming-conventions.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.