# 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