diff --git a/ENDPOINT-ROUTING.md b/ENDPOINT-ROUTING.md new file mode 100644 index 0000000..338e6ac --- /dev/null +++ b/ENDPOINT-ROUTING.md @@ -0,0 +1,332 @@ +# API Endpoint Routing Documentation + +**Project:** Trading Platform Backend +**Version:** 1.0.0 +**Last Updated:** 2026-01-26 + +## Overview + +This document describes the API endpoint routing structure for the Trading Platform backend. All endpoints follow RESTful conventions and are organized by module. + +## Base URL Structure + +``` +http://localhost:3080/api/v1 +``` + +- **Base Path:** `/api` +- **API Version:** `/v1` +- **Module Routes:** `/{module-name}` + +## Module Organization + +The API is organized into the following modules: + +| Module | Base Route | Description | +|--------|------------|-------------| +| Auth | `/api/v1/auth` | Authentication and authorization | +| Users | `/api/v1/users` | User management and profiles | +| Education | `/api/v1/education` | Educational courses and content | +| Trading | `/api/v1/trading` | Trading bots, signals, and positions | +| Investment | `/api/v1/investment` | Investment accounts and analytics | +| Portfolio | `/api/v1/portfolio` | Portfolio management | +| Payments | `/api/v1/payments` | Payment processing and subscriptions | +| ML | `/api/v1/ml` | Machine learning predictions | +| Agents | `/api/v1/agents` | Trading agent management | +| Notifications | `/api/v1/notifications` | User notifications | +| Admin | `/api/v1/admin` | Administrative functions | + +## Authentication & Authorization Module + +**Base Route:** `/api/v1/auth` + +### Public Endpoints (No Authentication Required) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/auth/register` | Register new user account | +| POST | `/auth/login` | Login with email/password | +| POST | `/auth/oauth/:provider/url` | Get OAuth authorization URL | +| POST | `/auth/oauth/:provider/callback` | OAuth callback handler | +| POST | `/auth/forgot-password` | Request password reset | +| POST | `/auth/reset-password` | Reset password with token | +| POST | `/auth/verify-email` | Verify email address | + +### Protected Endpoints (Authentication Required) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/auth/logout` | Logout current session | +| POST | `/auth/refresh` | Refresh access token | +| GET | `/auth/me` | Get current user info | +| POST | `/auth/change-password` | Change user password | +| POST | `/auth/2fa/setup` | Setup 2FA | +| POST | `/auth/2fa/enable` | Enable 2FA | +| POST | `/auth/2fa/verify` | Verify 2FA code | +| POST | `/auth/2fa/disable` | Disable 2FA | +| GET | `/auth/2fa/backup-codes` | Get backup codes | +| GET | `/auth/sessions` | List user sessions | +| DELETE | `/auth/sessions/:sessionId` | Revoke session | + +## Education Module + +**Base Route:** `/api/v1/education` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/education/courses` | List all courses | +| GET | `/education/courses/featured` | Get featured courses | +| GET | `/education/courses/search` | Search courses | +| GET | `/education/courses/:courseId` | Get course details | +| GET | `/education/courses/slug/:slug` | Get course by slug | +| POST | `/education/courses/:courseId/enroll` | Enroll in course | +| GET | `/education/courses/:courseId/progress` | Get course progress | +| GET | `/education/courses/:courseId/modules` | List course modules | +| GET | `/education/lessons/:lessonId` | Get lesson details | +| POST | `/education/lessons/:lessonId/complete` | Mark lesson complete | +| GET | `/education/quizzes/:quizId` | Get quiz details | +| POST | `/education/quizzes/:quizId/submit` | Submit quiz answers | +| GET | `/education/certificates` | List user certificates | +| GET | `/education/certificates/:certificateId` | Get certificate | +| GET | `/education/certificates/verify/:code` | Verify certificate | +| GET | `/education/my-courses` | List enrolled courses | + +## Trading Module + +**Base Route:** `/api/v1/trading` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/trading/bots` | List trading bots | +| GET | `/trading/bots/featured` | Get featured bots | +| GET | `/trading/bots/:botId` | Get bot details | +| POST | `/trading/bots/:botId/subscribe` | Subscribe to bot | +| GET | `/trading/bots/:botId/reviews` | Get bot reviews | +| GET | `/trading/signals` | List trading signals | +| GET | `/trading/signals/:signalId` | Get signal details | +| POST | `/trading/signals/:signalId/execute` | Execute signal | +| GET | `/trading/portfolio` | Get trading portfolio | +| GET | `/trading/positions` | List open positions | +| GET | `/trading/positions/:positionId` | Get position details | +| POST | `/trading/positions/:positionId/close` | Close position | +| GET | `/trading/history` | Get trading history | +| GET | `/trading/my-subscriptions` | List bot subscriptions | + +## Investment Module + +**Base Route:** `/api/v1/investment` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/investment/accounts` | List investment accounts | +| POST | `/investment/accounts` | Create new account | +| GET | `/investment/accounts/:accountId` | Get account details | +| PUT | `/investment/accounts/:accountId` | Update account | +| POST | `/investment/accounts/connect` | Connect trading account | +| GET | `/investment/performance` | Get performance metrics | +| GET | `/investment/analytics` | Get analytics data | + +## Portfolio Module + +**Base Route:** `/api/v1/portfolio` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/portfolio` | List user portfolios | +| POST | `/portfolio` | Create new portfolio | +| GET | `/portfolio/:portfolioId` | Get portfolio details | +| PUT | `/portfolio/:portfolioId` | Update portfolio | +| DELETE | `/portfolio/:portfolioId` | Delete portfolio | +| GET | `/portfolio/:portfolioId/allocations` | Get allocations | +| POST | `/portfolio/:portfolioId/allocations` | Add allocation | +| PUT | `/portfolio/:portfolioId/allocations/:id` | Update allocation | +| GET | `/portfolio/:portfolioId/performance` | Get performance data | +| GET | `/portfolio/:portfolioId/goals` | List goals | +| POST | `/portfolio/:portfolioId/goals` | Create goal | + +## Payments Module + +**Base Route:** `/api/v1/payments` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/payments` | List user payments | +| POST | `/payments/checkout` | Create checkout session | +| GET | `/payments/credits` | Get credit balance | +| POST | `/payments/credits/purchase` | Purchase credits | +| GET | `/payments/subscriptions` | List subscriptions | +| GET | `/payments/subscriptions/:id` | Get subscription details | +| POST | `/payments/subscriptions/:id/cancel` | Cancel subscription | +| GET | `/payments/invoices` | List invoices | +| GET | `/payments/invoices/:id` | Get invoice | +| GET | `/payments/invoices/:id/download` | Download invoice PDF | +| GET | `/payments/payment-methods` | List payment methods | +| POST | `/payments/payment-methods` | Add payment method | +| DELETE | `/payments/payment-methods/:id` | Remove payment method | +| POST | `/payments/webhooks/stripe` | Stripe webhook handler | + +## ML Module + +**Base Route:** `/api/v1/ml` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/ml/models` | List ML models | +| GET | `/ml/models/:modelId` | Get model details | +| POST | `/ml/predict` | Request prediction | +| GET | `/ml/predictions` | List predictions | +| GET | `/ml/predictions/:predictionId` | Get prediction details | +| GET | `/ml/signals` | Get ML-generated signals | + +## Admin Module + +**Base Route:** `/api/v1/admin` + +**⚠️ All admin endpoints require admin role** + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/admin/dashboard` | Get admin dashboard data | +| GET | `/admin/users` | List all users | +| GET | `/admin/users/:userId` | Get user details | +| PUT | `/admin/users/:userId` | Update user | +| DELETE | `/admin/users/:userId` | Delete user | +| GET | `/admin/courses` | List all courses | +| PUT | `/admin/courses/:courseId` | Update course | +| DELETE | `/admin/courses/:courseId` | Delete course | +| GET | `/admin/bots` | List all trading bots | +| PUT | `/admin/bots/:botId` | Update bot | +| DELETE | `/admin/bots/:botId` | Delete bot | +| GET | `/admin/transactions` | List all transactions | +| GET | `/admin/analytics` | Get system analytics | +| GET | `/admin/settings` | Get system settings | +| PUT | `/admin/settings` | Update system settings | + +## Route Files Organization + +Each module has its own route file that defines the endpoints: + +``` +src/modules/ +├── auth/ +│ └── auth.routes.ts # Authentication routes +├── users/ +│ └── users.routes.ts # User management routes +├── education/ +│ └── education.routes.ts # Education routes +├── trading/ +│ └── trading.routes.ts # Trading routes +├── investment/ +│ └── investment.routes.ts # Investment routes +├── portfolio/ +│ └── portfolio.routes.ts # Portfolio routes +├── payments/ +│ └── payments.routes.ts # Payment routes +├── ml/ +│ └── ml.routes.ts # ML routes +├── admin/ +│ └── admin.routes.ts # Admin routes +└── ... +``` + +## Route Constants + +All route paths are centralized in: +``` +src/shared/constants/routes.constants.ts +``` + +This file exports: +- `API_ROUTES` - Object containing all route definitions +- `HTTP_METHODS` - HTTP method constants +- `HTTP_STATUS` - HTTP status code constants + +## Middleware Stack + +Routes typically use the following middleware stack: + +1. **CORS** - Cross-origin resource sharing +2. **Rate Limiting** - API rate limiting +3. **Authentication** - JWT validation (protected routes) +4. **Authorization** - Role-based access control +5. **Validation** - Request body/params validation +6. **Error Handling** - Centralized error handling + +## Error Responses + +All endpoints return errors in this format: + +```json +{ + "success": false, + "error": { + "message": "Error description", + "code": "ERROR_CODE", + "field": "fieldName" // Optional, for validation errors + } +} +``` + +## Success Responses + +All endpoints return success in this format: + +```json +{ + "success": true, + "data": { + // Response data + }, + "message": "Success message" // Optional +} +``` + +## Pagination + +List endpoints support pagination with query parameters: + +``` +GET /api/v1/module/resource?page=1&limit=20&sortBy=createdAt&sortOrder=desc +``` + +Response includes metadata: + +```json +{ + "success": true, + "data": [...], + "meta": { + "page": 1, + "limit": 20, + "total": 100, + "totalPages": 5 + } +} +``` + +## Versioning Strategy + +- Current version: `v1` +- API version is specified in the URL: `/api/v1/...` +- Breaking changes will increment the version number +- Old versions will be maintained for 6 months after deprecation + +## Related Documentation + +- **API Constants:** `src/shared/constants/routes.constants.ts` +- **Swagger/OpenAPI:** Coming soon (ST2: Documentation Integration) +- **Postman Collection:** Coming soon +- **Module READMEs:** Each module's README.md file + +## Notes + +- This routing structure was audited and documented as part of coherence fix E-COH-007 (ST1.7) +- All endpoints follow RESTful conventions +- Authentication is handled via JWT tokens in Authorization header +- CORS is enabled for frontend origins +- Rate limiting is applied per IP address and user + +--- + +**Last Audit:** 2026-01-26 (ST1.7 - E-COH-007) +**Audited By:** Claude Opus 4.5