do-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