API versioning strategy

Severity: Optional

If the API uses versioning, it should follow a consistent strategy. Not all projects need versioning - internal APIs, early-stage projects, and single-consumer APIs may not require it.

Check automatically:

1. Check for version patterns in routes:

# URL path versioning
grep -rE "/v[0-9]+/" src/ app/ routes/ api/ --include="*.ts" --include="*.js" --include="*.py" --include="*.go" 2>/dev/null

# Check route definitions
grep -rE "('|\")/api/v[0-9]+|/v[0-9]+/|version.*[0-9]" src/ app/ routes/ 2>/dev/null

# Express/Fastify router prefixes
grep -rE "router.*v[0-9]|prefix.*v[0-9]|basePath.*v[0-9]" src/ app/ 2>/dev/null

2. Check for header-based versioning:

# Version headers
grep -rE "Accept-Version|API-Version|X-API-Version|api-version" src/ app/ lib/ 2>/dev/null

# Custom version extraction
grep -rE "req\.headers.*version|request\.headers.*version|getHeader.*version" src/ app/ 2>/dev/null

3. Check for versioning middleware/libraries:

# Node.js
grep -E "express-version-route|@fastify/versioning|express-routes-versioning" package.json 2>/dev/null

# Check OpenAPI spec version
grep -rE "^version:|\"version\":" openapi.yaml swagger.json api.yaml 2>/dev/null

4. Check for consistency:

# Find all route definitions and check if versioning is consistent
grep -rE "app\.(get|post|put|patch|delete)|router\.(get|post|put|patch|delete)" src/ app/ routes/ --include="*.ts" --include="*.js" 2>/dev/null | head -20

# Look for mixed patterns (some versioned, some not)
grep -rE "('|\")/api/" src/ app/ routes/ 2>/dev/null | grep -v "/v[0-9]" | head -10

Ask user:

• "Is this a public API that needs backward compatibility?"
• "Do you use URL versioning (/v1/) or header versioning?"
• "Are there multiple API versions currently active?"

Cross-reference with:

• API-002 (deprecation strategy if versions exist)
• DOC-001 (API documentation should mention versioning)

Pass criteria:

• Consistent versioning strategy (all versioned routes use same approach), OR
• No versioning (acceptable for internal/early-stage/single-consumer APIs)
• If public API with external consumers: versioning should exist

Fail criteria:

• Mixed versioning (some routes /v1/, some unversioned)
• Inconsistent strategy (URL for some, header for others)
• Public API with external consumers but no versioning

Evidence to capture:

• Versioning approach (URL path, header, or none)
• Sample versioned routes
• Whether API is public or internal
• Any consistency issues found

---