79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
# Data Transfer Objects (DTO)
|
|
|
|
## Overview
|
|
These definitions represent the strict contract between the Frontend (React) and Backend (Next.js API). They mirror the TypeScript interfaces found in `types.ts`.
|
|
|
|
## Core Entities
|
|
|
|
### 1. User DTO
|
|
**Type:** `UserDTO`
|
|
Used in authentication responses and author details.
|
|
|
|
| Field | Type | Description |
|
|
| :--- | :--- | :--- |
|
|
| `id` | `string` (UUID) | Unique identifier |
|
|
| `username` | `string` | Display name |
|
|
| `avatarUrl` | `string` | URL to profile image |
|
|
| `role` | `'USER' \| 'ADMIN' \| 'CREATOR'` | Permission level |
|
|
| `status` | `'ACTIVE' \| 'BANNED'` | Account standing |
|
|
|
|
### 2. Material DTO
|
|
**Type:** `MaterialDTO`
|
|
The main resource object.
|
|
|
|
| Field | Type | Description |
|
|
| :--- | :--- | :--- |
|
|
| `id` | `string` (UUID) | Unique identifier |
|
|
| `title` | `string` | Resource title |
|
|
| `description` | `string` | Short summary |
|
|
| `type` | `'CODE' \| 'ASSET_ZIP' \| 'VIDEO'` | Content category |
|
|
| `contentUrl` | `string?` | S3/CDN Link (Video/Zip) |
|
|
| `codeSnippet` | `string?` | Raw code string (Code only) |
|
|
| `language` | `string?` | e.g. 'typescript', 'python' |
|
|
| `author` | `UserDTO` | Nested author object |
|
|
| `stats` | `Object` | `{ views: number, downloads: number, favorites: number }` |
|
|
|
|
## Request Payloads
|
|
|
|
### Create Material Request
|
|
**POST** `/api/materials`
|
|
|
|
```typescript
|
|
interface CreateMaterialRequest {
|
|
title: string;
|
|
description: string;
|
|
type: 'CODE' | 'ASSET_ZIP' | 'VIDEO';
|
|
codeSnippet?: string; // Required if type is CODE
|
|
contentUrl?: string; // Required if type is VIDEO/ASSET
|
|
tags: string[];
|
|
}
|
|
```
|
|
|
|
### Update User Profile Request
|
|
**PATCH** `/api/users/me`
|
|
|
|
```typescript
|
|
interface UpdateProfileRequest {
|
|
username?: string;
|
|
avatarUrl?: string;
|
|
currentPassword?: string; // For security checks
|
|
newPassword?: string;
|
|
}
|
|
```
|
|
|
|
## Response Wrappers
|
|
|
|
**Generic API Response**
|
|
All API endpoints return data wrapped in this structure for consistent error handling.
|
|
|
|
```typescript
|
|
interface ApiResponse<T> {
|
|
success: boolean;
|
|
data?: T; // Present on success
|
|
error?: { // Present on failure
|
|
code: string; // e.g., 'AUTH_FAILED'
|
|
message: string; // Human readable
|
|
};
|
|
timestamp: string; // ISO Date
|
|
}
|
|
``` |