API Design

Strategy

• REST-first - All APIs follow REST conventions
• No GraphQL - Keep it simple
• JSON only - Request and response bodies
• Versioned - /api/v1/ prefix for all endpoints

URL Patterns

Response Format

All responses follow consistent structure:

// Success
{ "data": { ... }, "meta": { ... }, "error": null }

// Error
{ "data": null, "error": { "code": "ERROR_CODE", "message": "..." } }

Status Codes

Authentication

• MVP: Auth.js database sessions (Google SSO via Next.js)
• API: Tenant context passed via x-tenant-id header from authenticated Next.js frontend
• All API endpoints require TenantGuard validation

Authentication Flow (MVP)

Authentication is handled by Auth.js in Next.js, not by the NestJS API directly:

1. User clicks "Sign in with Google" on Next.js frontend
2. Auth.js handles OAuth flow, creates user/tenant via createUser event
3. Session stored in PostgreSQL via PrismaAdapter
4. Frontend passes x-tenant-id and x-system-role headers to API
5. NestJS TenantGuard and SystemRoleGuard validate requests

API Headers (from authenticated frontend)

// Headers sent by Next.js frontend to NestJS API
{
  'x-tenant-id': string      // From session.user.tenantId
  'x-system-role': string    // SYSTEM_ADMIN | HR_ADMIN | MANAGER | EMPLOYEE
}

Tenant Endpoint

Note: User registration/login is handled by Auth.js in Next.js, not the NestJS API. See Phase 01 for details.

Query Parameters

• Pagination: ?page=1&limit=20
• Filtering: ?status=active&departmentId=...
• Sorting: ?sort=-createdAt (prefix - for descending)
• Search: ?search=john

Key Rules

1. Tenant isolation - All endpoints scoped to tenant from x-tenant-id header
2. Consistent naming - Plural nouns for resources (/employees, not /employee)
3. Validation - All inputs validated with DTOs
4. Error details - Return field-level validation errors

See Phase 01 for auth implementation details