Source-Grounded API Usage: Verify Before You Code

SOURCE-GROUNDED API VERIFICATION

API UNDER REVIEW: User Management Service

DOCUMENT SOURCES
  Specification: openapi.yaml (v3.0.0, 342 lines)
  Implementation: src/api/users.js (427 lines)
  Live deployment: api.example.com/users
  Test coverage: tests/users.test.js (18 tests)

FINDINGS BY ENDPOINT

Endpoint 1: GET /users/{id}
  Spec definition (line 87-112):
    Parameter: id (integer, required)
    Response 200: User object with fields {id, email, created_at, role}
    Response 404: Error object with fields {code, message}
  
  Implementation check:
    Route exists at line 45: ✓
    Parameter validation: ✓ Validates integer type
    Response schema: ✓ Returns all 4 required fields
    Error handling: MISMATCH - Returns {error_message, status_code} instead of {code, message}
    Flag: Response error schema does not match spec. See lines 67-72 of users.js

Endpoint 2: POST /users
  Spec definition (line 114-148):
    Request body: {email (string), password (string), role (string, enum: admin/user)}
    Response 201: Created User object
    Response 400: Validation error
  
  Implementation check:
    Route exists: ✓
    Request validation: ✓ Checks email format, password length
    Role validation: MISMATCH - Implementation allows role="moderator" but spec only allows admin/user
    Flag: Role enum not restricted per spec. See line 78 of users.js

Endpoint 3: PUT /users/{id}
  Spec definition (line 150-180):
    Allowed updates: email, password, role
    Restriction: Users can only update themselves unless admin
  
  Implementation check:
    Authorization logic: DEVIATION - Implementation checks user_id === auth.id but spec says users can only update themselves unless admin
    Schema alignment: ✓ All updatable fields match
    Flag: Auth check does not match permission hierarchy in spec. See line 112 of users.js

DEVIATION SUMMARY
  Total deviations found: 3
    Type 1 - Response schema mismatch: 1 instance
    Type 2 - Validation mismatch: 1 instance
    Type 3 - Authorization logic mismatch: 1 instance
  
  Severity breakdown:
    Critical (breaks clients): 1 (response schema)
    Medium (security/logic): 1 (authorization)
    Low (validation strictness): 1 (role enum)

RECOMMENDATIONS
  1. FIX IMMEDIATELY: Align error response schema to spec {code, message} format
     Where: users.js lines 67-72
     Impact: Live clients expecting {code, message} will fail
  
  2. FIX BEFORE DEPLOY: Restrict role enum to admin/user only
     Where: users.js line 78 (add enum validation)
     Impact: Security - unknown roles could cause privilege escalation
  
  3. CLARIFY WITH PRODUCT: Confirm authorization model in spec
     Current implementation allows self-edit only; spec suggests admin override
     If admin override needed, add new endpoint or document in spec

COMPLIANCE SCORE: 73% (matches spec)
  Passing: 15 of 18 checks
  Deviations: 3 of 18 checks
  Recommendation: Address critical + medium issues before production release