Skip to content

Commit f3c1497

Browse files
pphatdevpphatdev
committed
docs: Add a comprehensive Postman collection for the CDN API and a guide for the avatar upload endpoint.
1 parent 34857b5 commit f3c1497

File tree

3 files changed

+272
-85
lines changed

3 files changed

+272
-85
lines changed

‎README.md‎

Lines changed: 112 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,15 @@ CDN API is a production-ready content delivery network service that provides int
5555
## ✨ Features
5656

5757
### 🖼️ Image Management
58+
5859
- **Intelligent Optimization**: Automatic image compression and format conversion
5960
- **Multi-format Support**: JPEG, PNG, WebP, AVIF, GIF, TIFF
6061
- **Responsive Images**: Generate multiple sizes for responsive design
6162
- **Caching**: Built-in image caching for improved performance
6263
- **Metadata Extraction**: EXIF data preservation and extraction
6364

6465
### 📁 File Management
66+
6567
- **Secure Upload**: Validated file uploads with type checking
6668
- **Folder Organization**: Hierarchical folder structure support
6769
- **File Operations**: Move, delete, rename, and search files
@@ -71,6 +73,7 @@ CDN API is a production-ready content delivery network service that provides int
7173
- **Metadata Storage**: File metadata and tags in SQLite database
7274

7375
### 🔐 Authentication & Authorization
76+
7477
- **JWT Authentication**: Secure token-based authentication
7578
- **Role-Based Access**: Admin, user, and viewer roles
7679
- **Session Management**: Active session tracking with refresh tokens
@@ -80,6 +83,7 @@ CDN API is a production-ready content delivery network service that provides int
8083
- **Default Admin**: Auto-created admin account for initial setup
8184

8285
### 💾 Database & Migrations
86+
8387
- **SQLite Database**: Lightweight, serverless database with Drizzle ORM
8488
- **Type-Safe Queries**: Full TypeScript support with Drizzle
8589
- **Migration System**: Timestamp-based schema migration tracking
@@ -88,6 +92,7 @@ CDN API is a production-ready content delivery network service that provides int
8892
- **Schema Export**: Export database schema for documentation
8993

9094
### 🔒 Security & Performance
95+
9196
- **Rate Limiting**: Configurable rate limits for all endpoints
9297
- Image uploads: 30 requests per 15 minutes
9398
- File uploads: 15 requests per 15 minutes
@@ -96,12 +101,14 @@ CDN API is a production-ready content delivery network service that provides int
96101
- **Input Validation**: Comprehensive request validation
97102

98103
### 📊 Monitoring & Analytics
104+
99105
- **Storage Statistics**: Real-time storage usage analytics
100106
- **File Type Analysis**: Breakdown by file type and folder
101107
- **Largest Files Tracking**: Identify storage-heavy assets
102108
- **Performance Metrics**: Response time and throughput monitoring
103109

104110
### 🎨 Web Dashboard
111+
105112
- **Authentication**: Login page with JWT-based authentication
106113
- **Dashboard**: Overview of storage usage and recent activity
107114
- **File Browser**: Visual interface for browsing and managing files with breadcrumb navigation
@@ -223,60 +230,62 @@ The server will be available at `http://localhost:3000` (or your configured port
223230

224231
```json
225232
{
226-
"app": {
227-
"name": "CDN API",
228-
"env": "development" // "development" or "production"
229-
},
230-
"port": 3000, // Server port
231-
"directories": [
232-
"./storage/**/**" // Storage directory pattern
233+
"app": {
234+
"name": "CDN API",
235+
"env": "development" // "development" or "production"
236+
},
237+
"port": 3000, // Server port
238+
"directories": [
239+
"./storage/**/**" // Storage directory pattern
240+
],
241+
"allow": {
242+
"origins": [
243+
// Allowed CORS origins
244+
"http://localhost:3000",
245+
"http://localhost:5173"
233246
],
234-
"allow": {
235-
"origins": [ // Allowed CORS origins
236-
"http://localhost:3000",
237-
"http://localhost:5173"
238-
],
239-
"patterns": [ // Regex patterns for origins
240-
"^https?://.*\\.stackdev\\.cloud$"
241-
]
242-
},
243-
"database": {
244-
"dbPath": "src/data/app.db", // SQLite database path
245-
"autoRunMigrations": true, // Run migrations on startup
246-
"autoRunSeeds": false // Run seeds on startup
247-
},
248-
"auth": {
249-
"jwtSecret": "your-super-secret-jwt-key-min-32-characters-long",
250-
"jwtExpiresIn": "1h", // Access token expiration
251-
"refreshTokenExpiresIn": "7d", // Refresh token expiration
252-
"bcryptRounds": 12, // Password hashing rounds
253-
"maxLoginAttempts": 5, // Failed login limit
254-
"lockoutDuration": 15, // Account lockout minutes
255-
"maxSessionsPerUser": 5 // Max concurrent sessions
256-
}
247+
"patterns": [
248+
// Regex patterns for origins
249+
"^https?://.*\\.stackdev\\.cloud$"
250+
]
251+
},
252+
"database": {
253+
"dbPath": "src/data/app.db", // SQLite database path
254+
"autoRunMigrations": true, // Run migrations on startup
255+
"autoRunSeeds": false // Run seeds on startup
256+
},
257+
"auth": {
258+
"jwtSecret": "your-super-secret-jwt-key-min-32-characters-long",
259+
"jwtExpiresIn": "1h", // Access token expiration
260+
"refreshTokenExpiresIn": "7d", // Refresh token expiration
261+
"bcryptRounds": 12, // Password hashing rounds
262+
"maxLoginAttempts": 5, // Failed login limit
263+
"lockoutDuration": 15, // Account lockout minutes
264+
"maxSessionsPerUser": 5 // Max concurrent sessions
265+
}
257266
}
258267
```
259268

260269
### Configuration Options
261270

262-
| Option | Type | Description | Default |
263-
|--------|------|-------------|---------|
264-
| `app.name` | string | Application name | "CDN API" |
265-
| `app.env` | string | Environment mode | "development" |
266-
| `port` | number | Server port | 3000 |
267-
| `directories` | array | Storage directory patterns | `["./storage/**/**"]` |
268-
| `allow.origins` | array | Exact CORS origins | `[]` |
269-
| `allow.patterns` | array | Regex patterns for CORS | `[]` |
270-
| `database.dbPath` | string | SQLite database file path | "src/data/app.db" |
271-
| `database.autoRunMigrations` | boolean | Auto-run migrations on startup | true |
272-
| `database.autoRunSeeds` | boolean | Auto-run seeds on startup | false |
273-
| `auth.jwtSecret` | string | JWT secret key (min 32 chars) | Required |
274-
| `auth.jwtExpiresIn` | string | Access token TTL | "1h" |
275-
| `auth.refreshTokenExpiresIn` | string | Refresh token TTL | "7d" |
276-
| `auth.bcryptRounds` | number | Password hashing strength | 12 |
277-
| `auth.maxLoginAttempts` | number | Failed login threshold | 5 |
278-
| `auth.lockoutDuration` | number | Lockout duration (minutes) | 15 |
279-
| `auth.maxSessionsPerUser` | number | Max concurrent sessions per user | 5 |
271+
| Option | Type | Description | Default |
272+
| ---------------------------- | ------- | -------------------------------- | --------------------- |
273+
| `app.name` | string | Application name | "CDN API" |
274+
| `app.env` | string | Environment mode | "development" |
275+
| `port` | number | Server port | 3000 |
276+
| `directories` | array | Storage directory patterns | `["./storage/**/**"]` |
277+
| `allow.origins` | array | Exact CORS origins | `[]` |
278+
| `allow.patterns` | array | Regex patterns for CORS | `[]` |
279+
| `database.dbPath` | string | SQLite database file path | "src/data/app.db" |
280+
| `database.autoRunMigrations` | boolean | Auto-run migrations on startup | true |
281+
| `database.autoRunSeeds` | boolean | Auto-run seeds on startup | false |
282+
| `auth.jwtSecret` | string | JWT secret key (min 32 chars) | Required |
283+
| `auth.jwtExpiresIn` | string | Access token TTL | "1h" |
284+
| `auth.refreshTokenExpiresIn` | string | Refresh token TTL | "7d" |
285+
| `auth.bcryptRounds` | number | Password hashing strength | 12 |
286+
| `auth.maxLoginAttempts` | number | Failed login threshold | 5 |
287+
| `auth.lockoutDuration` | number | Lockout duration (minutes) | 15 |
288+
| `auth.maxSessionsPerUser` | number | Max concurrent sessions per user | 5 |
280289

281290
### Storage Structure
282291

@@ -348,6 +357,7 @@ npm run db:studio
348357
```
349358

350359
Then visit http://localhost:4983/ to:
360+
351361
- Browse all tables and data
352362
- Run queries visually
353363
- Edit records directly
@@ -378,6 +388,7 @@ cp src/data/app.db src/data/app.db.backup
378388
```
379389

380390
Or use the API endpoint:
391+
381392
```bash
382393
curl -X POST http://localhost:3000/api/database/backup
383394
```
@@ -410,6 +421,7 @@ npm run css
410421
### Default Admin Credentials
411422

412423
After running migrations, a default admin account is created:
424+
413425
- **Username**: `admin`
414426
- **Password**: `admin123`
415427
- **Email**: `admin@stackdev.cloud`
@@ -482,33 +494,39 @@ curl http://localhost:3000/api/auth/me \
482494

483495
### Endpoints Overview
484496

485-
| Category | Endpoint | Method | Description | Auth Required |
486-
|----------|----------|--------|-------------|---------------|
487-
| **Health** | `/` | GET | API welcome message | No |
488-
| **Health** | `/version` | GET | Get API version info | No |
489-
| **Auth** | `/auth/login` | POST | User login (rate limited) | No |
490-
| **Auth** | `/auth/logout` | POST | Logout current session | Yes |
491-
| **Auth** | `/auth/logout-all` | POST | Logout all sessions | Yes |
492-
| **Auth** | `/auth/me` | GET | Get current user info | Yes |
493-
| **Images** | `/image/upload` | POST | Upload images (rate limited) | Optional |
494-
| **Images** | `/image/*` | GET | Retrieve optimized images | No |
495-
| **Files** | `/file/upload` | POST | Upload files (rate limited) | Optional |
496-
| **Files** | `/file/search` | GET | Search files by name | No |
497-
| **Files** | `/file/move` | PUT | Move files/folders | Optional |
498-
| **Files** | `/file/delete` | DELETE | Delete files | Optional |
499-
| **Files** | `/file/download/*` | GET | Download files | No |
500-
| **Files** | `/file/preview/*` | GET | Preview documents | No |
501-
| **Folders** | `/folder` | GET | Get folder structure | No |
502-
| **Database** | `/database/files` | GET | Get files database | No |
503-
| **Database** | `/database/stats` | GET | Database statistics | No |
504-
| **Database** | `/database/search` | GET | Search database | No |
505-
| **Database** | `/database/backup` | POST | Backup database | Optional |
506-
| **Storage** | `/storage` | GET | Full storage statistics | No |
507-
| **Storage** | `/storage/summary` | GET | Quick storage summary | No |
497+
| Category | Endpoint | Method | Description | Auth Required |
498+
| ------------ | ------------------ | ------ | ---------------------------- | ------------- |
499+
| **Health** | `/` | GET | API welcome message | No |
500+
| **Health** | `/version` | GET | Get API version info | No |
501+
| **Auth** | `/auth/login` | POST | User login (rate limited) | No |
502+
| **Auth** | `/auth/logout` | POST | Logout current session | Yes |
503+
| **Auth** | `/auth/logout-all` | POST | Logout all sessions | Yes |
504+
| **Auth** | `/auth/me` | GET | Get current user info | Yes |
505+
| **Auth** | `/auth/me/avatar` | POST | Upload user avatar | Yes |
506+
| **Images** | `/image/upload` | POST | Upload images (rate limited) | Optional |
507+
| **Images** | `/image/*` | GET | Retrieve optimized images | No |
508+
| **Files** | `/file/upload` | POST | Upload files (rate limited) | Optional |
509+
| **Files** | `/file/search` | GET | Search files by name | No |
510+
| **Files** | `/file/move` | PUT | Move files/folders | Optional |
511+
| **Files** | `/file/delete` | DELETE | Delete files | Optional |
512+
| **Files** | `/file/download/*` | GET | Download files | No |
513+
| **Files** | `/file/preview/*` | GET | Preview documents | No |
514+
| **Folders** | `/folder` | GET | Get folder structure | No |
515+
| **Database** | `/database/files` | GET | Get files database | No |
516+
| **Database** | `/database/stats` | GET | Database statistics | No |
517+
| **Database** | `/database/search` | GET | Search database | No |
518+
| **Database** | `/database/backup` | POST | Backup database | Optional |
519+
| **Users** | `/auth/users` | GET | List all users (Admin) | Yes |
520+
| **Users** | `/auth/users` | POST | Create new user (Admin) | Yes |
521+
| **Users** | `/auth/users/:id` | PUT | Update user (Admin) | Yes |
522+
| **Users** | `/auth/users/:id` | DELETE | Delete user (Admin) | Yes |
523+
| **Storage** | `/storage` | GET | Full storage statistics | No |
524+
| **Storage** | `/storage/summary` | GET | Quick storage summary | No |
508525

509526
### Detailed API Documentation
510527

511528
For comprehensive API documentation with examples, see:
529+
512530
- [Migration Guide](docs/how-to-use/MIGRATION_GUIDE.md) - Database migration system
513531
- [Image Upload Endpoint](docs/how-to-use/image-upload-endpoint.md)
514532
- [File Upload Endpoint](docs/how-to-use/file-upload-endpoint.md)
@@ -518,10 +536,12 @@ For comprehensive API documentation with examples, see:
518536
- [Move File Endpoint](docs/how-to-use/move-file-endpoint.md)
519537
- [Search Filename](docs/how-to-use/search-filename.md)
520538
- [Rate Limiting](docs/how-to-use/rate-limiting.md)
539+
- [Avatar Upload](docs/how-to-use/avatar-upload-endpoint.md)
521540

522541
### Postman Collection
523542

524543
Import the Postman collection for testing:
544+
525545
```
526546
docs/collections/collection.postman_collection.json
527547
```
@@ -530,19 +550,19 @@ docs/collections/collection.postman_collection.json
530550

531551
The application includes a full-featured web interface accessible via browser:
532552

533-
| Route | Description | Auth Required |
534-
|-------|-------------|---------------|
535-
| `/` | Dashboard overview with storage stats | Yes |
536-
| `/login` | User authentication page | No |
537-
| `/files` | File browser and manager | Yes |
538-
| `/files/*` | Navigate through folder structure | Yes |
539-
| `/starred` | Quick access to starred files | Yes |
540-
| `/recent` | Recently accessed files | Yes |
541-
| `/detail` | Detailed file information | Yes |
542-
| `/share` | Shared files management | Yes |
543-
| `/upload` | File upload interface | Yes |
544-
| `/upload/history` | Upload activity history | Yes |
545-
| `/users` | User management (Admin only) | Yes |
553+
| Route | Description | Auth Required |
554+
| ----------------- | ------------------------------------- | ------------- |
555+
| `/` | Dashboard overview with storage stats | Yes |
556+
| `/login` | User authentication page | No |
557+
| `/files` | File browser and manager | Yes |
558+
| `/files/*` | Navigate through folder structure | Yes |
559+
| `/starred` | Quick access to starred files | Yes |
560+
| `/recent` | Recently accessed files | Yes |
561+
| `/detail` | Detailed file information | Yes |
562+
| `/share` | Shared files management | Yes |
563+
| `/upload` | File upload interface | Yes |
564+
| `/upload/history` | Upload activity history | Yes |
565+
| `/users` | User management (Admin only) | Yes |
546566

547567
**Note**: Web authentication is handled via JWT tokens stored in browser cookies. Users are automatically redirected to `/login` if not authenticated.
548568

@@ -553,6 +573,7 @@ The application includes a full-featured web interface accessible via browser:
553573
### Project Scripts
554574

555575
#### Development
576+
556577
```bash
557578
# Development server with hot reload
558579
npm run dev
@@ -571,6 +592,7 @@ npm start
571592
```
572593

573594
#### Database Management
595+
574596
```bash
575597
# Run all pending migrations
576598
npm run migrate:up
@@ -816,6 +838,7 @@ docs/collections/collection.postman_collection.json
816838
### Testing Checklist
817839

818840
#### Authentication Tests
841+
819842
- [ ] User login with valid credentials
820843
- [ ] Login rate limiting (5 attempts)
821844
- [ ] Account locking after failed attempts
@@ -825,6 +848,7 @@ docs/collections/collection.postman_collection.json
825848
- [ ] Current user info retrieval
826849

827850
#### File Operations Tests
851+
828852
- [ ] Image upload with various formats (JPEG, PNG, WebP, TIFF)
829853
- [ ] File upload with different file types
830854
- [ ] File search by name
@@ -834,6 +858,7 @@ docs/collections/collection.postman_collection.json
834858
- [ ] Document preview generation
835859

836860
#### System Tests
861+
837862
- [ ] Rate limiting verification (all endpoints)
838863
- [ ] CORS headers validation
839864
- [ ] Storage statistics accuracy
@@ -843,6 +868,7 @@ docs/collections/collection.postman_collection.json
843868
- [ ] Session management
844869

845870
#### Database Tests
871+
846872
- [ ] Migration execution
847873
- [ ] Rollback functionality
848874
- [ ] Seed data integrity
@@ -902,6 +928,7 @@ footer
902928
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
903929

904930
Example:
931+
905932
```
906933
feat(storage): add file type filtering to storage stats
907934
@@ -922,6 +949,7 @@ This project is licensed under the ISC License - see the [LICENSE](LICENSE) file
922949
## 👨‍💻 Author
923950

924951
**Sophat (PPhat)**
952+
925953
- GitHub: [@pphatdev](https://github.com/pphatdev)
926954
- Website: [stackdev.cloud](https://stackdev.cloud)
927955

0 commit comments

Comments
 (0)