Magic numbers for status or type fields — status: 1, role: 3 — are opaque to every consumer reading the response. Mixed enum formats across endpoints (SCREAMING_SNAKE on one, snake_case on another) mean consumers must maintain a lookup table per endpoint just to decode the same semantic concept. This directly violates iso-25010:2011 maintainability.modifiability: adding a new status value requires updating documentation, clients, and any code that pattern-matches on string values.
Medium because inconsistent enum formats create consumer confusion and maintenance overhead without enabling direct security exploitation.
Choose one enum format — SCREAMING_SNAKE_CASE is the REST convention for constants — and apply it globally. Replace magic numbers with readable strings:
// Before -- inconsistent enums and magic numbers:
{ "status": "active", "role": 3, "plan": "PREMIUM" }
// After -- consistent SCREAMING_SNAKE throughout:
{ "status": "ACTIVE", "role": "ADMIN", "plan": "PREMIUM" }
Search your codebase for numeric values used as type discriminators (status: 1, type: 2) and replace them with string constants. Update your schema definitions and client-side switch statements in the same pass.
ID: api-design.naming-conventions.enum-naming
Severity: medium
What to look for: Examine fields that represent fixed sets of values (status fields, type fields, role fields). Check whether enum values use a consistent format: SCREAMING_SNAKE_CASE ("PENDING", "IN_PROGRESS"), snake_case ("pending", "in_progress"), kebab-case ("pending", "in-progress"), or camelCase ("pending", "inProgress"). Also check: are enum values strings (good for readability) or magic numbers (bad -- status: 1 tells the consumer nothing)?
Pass criteria: Enumerate all enum-like fields (status, type, role, category, state) across every endpoint. Enum/constant values across the API use one consistent format with at least 90% using the same casing style. No magic numbers for status or type fields -- all use readable string values. Report the count of enum fields found and the format used by each.
Fail criteria: Mixed enum formats across endpoints (e.g., status: "ACTIVE" in one endpoint, type: "premium_user" in another). Or magic numbers used for status/type fields (status: 1, role: 3). Quote the actual enum values found in each format.
Skip (N/A) when: No enum-like fields found in any response (no status, type, role, or similar fixed-value fields).
Detail on fail: Identify the inconsistency (e.g., "User status uses SCREAMING_SNAKE (ACTIVE, SUSPENDED) but order status uses lowercase (pending, shipped). Payment type uses magic numbers (type: 1, type: 2). 3 formats across 5 enum fields."). Max 500 chars.
Remediation: Choose one format for all enum values and apply it globally. SCREAMING_SNAKE_CASE is the most common for API enums because it visually distinguishes constants from regular string values.
// Before -- inconsistent enums:
{ "status": "active", "role": 3, "plan": "PREMIUM" }
// After -- consistent SCREAMING_SNAKE:
{ "status": "ACTIVE", "role": "ADMIN", "plan": "PREMIUM" }