Validate Api Contracts

Requirements

1. Frontend Interface Validation

• Always define TypeScript interfaces that match exact backend response structure
• Include ALL fields returned by backend, including nested objects and metadata
• Validate both success and error response formats
• Example:

// ❌ WRONG - Missing authentication fields
interface UserResponse {
  id: number;
  username: string;
  email: string;
}

// ✅ CORRECT - Matches backend response exactly
interface UserResponse {
  user: {
    id: number;
    username: string;
    email: string;
    first_name?: string;
    last_name?: string;
    // ... all user fields
  };
  authenticated: boolean;
  token_valid: boolean;
  token_expires_at?: string;
}

2. Response Validation Logic

• Never assume HTTP 200 means success - always check response data fields
• Validate authentication/authorization flags in response
• Handle nested response structures correctly
• Example:

// ❌ WRONG - Only checking HTTP status
if (response.status === 200 && response.data) {
  setUser(response.data); // Assumes flat structure
}

// ✅ CORRECT - Full validation with nested structure
if (response.status === 200 && response.data && 
    response.data.authenticated && response.data.token_valid) {
  setUser(response.data.user); // Correctly accessing nested user
}

3. Documentation Requirements

• Document exact API response formats in Architecture_FULL.md
• Include example JSON responses for all authentication endpoints
• Specify frontend validation requirements
• Update documentation when API contracts change

4. Testing Requirements

• Write integration tests that validate actual API responses
• Test both success and failure scenarios
• Verify frontend handles all response fields correctly
• Include API contract tests in continuous testing

Prevention Checklist

Before implementing frontend API calls:
- [ ] Check Architecture_FULL.md for documented response format
- [ ] Define TypeScript interface matching exact backend response
- [ ] Implement full response validation (not just HTTP status)
- [ ] Test with actual backend responses
- [ ] Update documentation if response format differs

Before deploying API changes:
- [ ] Verify frontend interfaces match new backend response
- [ ] Update all affected frontend validation logic
- [ ] Run integration tests to validate contract compatibility
- [ ] Update Architecture_FULL.md with new response formats

Common Pitfalls to Avoid

1. Assuming flat response structure - Many APIs return nested objects
2. Only checking HTTP status - 200 OK doesn't guarantee valid data
3. Missing authentication flags - Backend may return success with auth failures
4. Outdated interfaces - Frontend types drift from backend reality
5. No integration testing - Unit tests don't catch contract mismatches