first commit
This commit is contained in:
364
API_ENDPOINTS.md
Normal file
364
API_ENDPOINTS.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# TurboTrades API Endpoints Reference
|
||||
|
||||
Complete list of all available API endpoints with examples.
|
||||
|
||||
---
|
||||
|
||||
## Base URL
|
||||
|
||||
- **Development**: `http://localhost:3000`
|
||||
- **Frontend Proxy**: `http://localhost:5173/api` (proxies to backend)
|
||||
|
||||
---
|
||||
|
||||
## Authentication Endpoints
|
||||
|
||||
### `/auth/*`
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| GET | `/auth/steam` | Initiate Steam login | No |
|
||||
| GET | `/auth/steam/return` | Steam OAuth callback | No |
|
||||
| GET | `/auth/steam/test` | Test Steam config | No |
|
||||
| GET | `/auth/me` | Get current user | Yes (Access Token) |
|
||||
| POST | `/auth/refresh` | Refresh access token | Yes (Refresh Token) |
|
||||
| POST | `/auth/logout` | Logout user | Yes (Access Token) |
|
||||
| GET | `/auth/verify` | Verify token validity | Yes (Access Token) |
|
||||
| GET | `/auth/decode-token` | Decode JWT token (debug) | No |
|
||||
|
||||
### Example Usage:
|
||||
|
||||
```bash
|
||||
# Login via Steam (opens browser)
|
||||
curl http://localhost:3000/auth/steam
|
||||
|
||||
# Get current user (requires auth)
|
||||
curl http://localhost:3000/auth/me \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
|
||||
# Refresh token
|
||||
curl -X POST http://localhost:3000/auth/refresh \
|
||||
-H "Cookie: refreshToken=YOUR_REFRESH_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Endpoints
|
||||
|
||||
### `/user/*`
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| GET | `/user/profile` | Get user profile | Yes |
|
||||
| PATCH | `/user/email` | Update email address | Yes |
|
||||
| GET | `/user/verify-email/:token` | Verify email | No |
|
||||
| PATCH | `/user/trade-url` | Update Steam trade URL | Yes |
|
||||
| GET | `/user/balance` | Get user balance | Yes |
|
||||
| GET | `/user/stats` | Get user statistics | Yes |
|
||||
| PATCH | `/user/intercom` | Update intercom ID | Yes |
|
||||
| GET | `/user/:steamId` | Get public user profile | No |
|
||||
|
||||
### Example Usage:
|
||||
|
||||
```bash
|
||||
# Get profile
|
||||
curl http://localhost:3000/user/profile \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
|
||||
# Update email
|
||||
curl -X PATCH http://localhost:3000/user/email \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "user@example.com"}'
|
||||
|
||||
# Update trade URL
|
||||
curl -X PATCH http://localhost:3000/user/trade-url \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"tradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=123&token=abc"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Two-Factor Authentication (2FA) Endpoints
|
||||
|
||||
### `/user/2fa/*`
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| POST | `/user/2fa/setup` | Generate QR code & secret | Yes |
|
||||
| POST | `/user/2fa/verify` | Verify code & enable 2FA | Yes |
|
||||
| POST | `/user/2fa/disable` | Disable 2FA | Yes |
|
||||
|
||||
### Example Usage:
|
||||
|
||||
```bash
|
||||
# Setup 2FA (get QR code)
|
||||
curl -X POST http://localhost:3000/user/2fa/setup \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
|
||||
# Verify 2FA code
|
||||
curl -X POST http://localhost:3000/user/2fa/verify \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "123456"}'
|
||||
|
||||
# Disable 2FA
|
||||
curl -X POST http://localhost:3000/user/2fa/disable \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"password": "123456"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Management Endpoints
|
||||
|
||||
### `/user/sessions/*`
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| GET | `/user/sessions` | Get all active sessions | Yes |
|
||||
| DELETE | `/user/sessions/:sessionId` | Revoke specific session | Yes |
|
||||
| POST | `/user/sessions/revoke-all` | Revoke all other sessions | Yes |
|
||||
|
||||
### Example Usage:
|
||||
|
||||
```bash
|
||||
# Get all sessions
|
||||
curl http://localhost:3000/user/sessions \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
|
||||
# Revoke specific session
|
||||
curl -X DELETE http://localhost:3000/user/sessions/SESSION_ID \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
|
||||
# Revoke all other sessions
|
||||
curl -X POST http://localhost:3000/user/sessions/revoke-all \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Market Endpoints
|
||||
|
||||
### `/market/*`
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| GET | `/market/items` | Get marketplace items | No |
|
||||
| GET | `/market/items/:id` | Get item details | No |
|
||||
| GET | `/market/featured` | Get featured items | No |
|
||||
| GET | `/market/recent-sales` | Get recent sales | No |
|
||||
| GET | `/market/stats` | Get market statistics | No |
|
||||
| POST | `/market/purchase/:id` | Purchase an item | Yes |
|
||||
|
||||
### Example Usage:
|
||||
|
||||
```bash
|
||||
# Get all items
|
||||
curl http://localhost:3000/market/items
|
||||
|
||||
# Get items with filters
|
||||
curl "http://localhost:3000/market/items?game=cs2&minPrice=10&maxPrice=100&limit=20"
|
||||
|
||||
# Get featured items
|
||||
curl http://localhost:3000/market/featured
|
||||
|
||||
# Get item details
|
||||
curl http://localhost:3000/market/items/ITEM_ID
|
||||
|
||||
# Purchase item
|
||||
curl -X POST http://localhost:3000/market/purchase/ITEM_ID \
|
||||
-H "Cookie: accessToken=YOUR_TOKEN"
|
||||
|
||||
# Get market stats
|
||||
curl http://localhost:3000/market/stats
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebSocket Endpoint
|
||||
|
||||
### `/ws`
|
||||
|
||||
Real-time updates via WebSocket.
|
||||
|
||||
```javascript
|
||||
// Connect to WebSocket
|
||||
const ws = new WebSocket('ws://localhost:3000/ws');
|
||||
|
||||
// Listen for messages
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Received:', data);
|
||||
};
|
||||
|
||||
// Send ping
|
||||
ws.send(JSON.stringify({ type: 'ping' }));
|
||||
```
|
||||
|
||||
**Events:**
|
||||
- `listing_update` - Item listing updated
|
||||
- `listing_removed` - Item removed from market
|
||||
- `listing_added` - New item added to market
|
||||
- `price_update` - Item price changed
|
||||
- `market_update` - Bulk market updates
|
||||
- `pong` - Response to ping
|
||||
|
||||
---
|
||||
|
||||
## Testing from Frontend
|
||||
|
||||
### Using Axios (already configured):
|
||||
|
||||
```javascript
|
||||
import axios from '@/utils/axios'
|
||||
|
||||
// Get user profile
|
||||
const response = await axios.get('/api/user/profile', {
|
||||
withCredentials: true
|
||||
})
|
||||
|
||||
// Update email
|
||||
await axios.patch('/api/user/email', {
|
||||
email: 'user@example.com'
|
||||
}, {
|
||||
withCredentials: true
|
||||
})
|
||||
|
||||
// Setup 2FA
|
||||
const response = await axios.post('/api/user/2fa/setup', {}, {
|
||||
withCredentials: true
|
||||
})
|
||||
|
||||
// Get sessions
|
||||
const response = await axios.get('/api/user/sessions', {
|
||||
withCredentials: true
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### 1. "Unauthorized" Error
|
||||
|
||||
**Cause**: No access token provided or token expired.
|
||||
|
||||
**Solution**:
|
||||
- Login via Steam first: `http://localhost:3000/auth/steam`
|
||||
- Ensure cookies are being sent: `withCredentials: true`
|
||||
- Check if token is expired (15 minutes lifetime)
|
||||
- Use refresh token to get new access token
|
||||
|
||||
### 2. "Route not found"
|
||||
|
||||
**Cause**: Incorrect URL or route not registered.
|
||||
|
||||
**Solution**:
|
||||
- Check the route prefix (`/auth`, `/user`, `/market`)
|
||||
- Verify the HTTP method (GET, POST, PATCH, DELETE)
|
||||
- Check backend logs for route registration
|
||||
|
||||
### 3. CORS Issues
|
||||
|
||||
**Cause**: Frontend and backend on different ports.
|
||||
|
||||
**Solution**:
|
||||
- Ensure `CORS_ORIGIN=http://localhost:5173` in `.env`
|
||||
- Restart backend after changing `.env`
|
||||
- Use frontend proxy: `/api/*` instead of direct backend URL
|
||||
|
||||
### 4. Sessions Not Working
|
||||
|
||||
**Cause**: Session model not properly imported or MongoDB issue.
|
||||
|
||||
**Solution**:
|
||||
- Check MongoDB is running: `mongod`
|
||||
- Verify Session model exists: `models/Session.js`
|
||||
- Check backend logs for session creation errors
|
||||
- Ensure TTL index is created on `expiresAt` field
|
||||
|
||||
---
|
||||
|
||||
## Response Formats
|
||||
|
||||
### Success Response:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response:
|
||||
```json
|
||||
{
|
||||
"error": "ErrorType",
|
||||
"message": "Human readable error message",
|
||||
"details": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
1. User clicks "Login with Steam" → `/auth/steam`
|
||||
2. Redirects to Steam OpenID
|
||||
3. User authenticates on Steam
|
||||
4. Steam redirects back → `/auth/steam/return`
|
||||
5. Backend generates JWT tokens
|
||||
6. Sets `accessToken` and `refreshToken` cookies
|
||||
7. Redirects to frontend → `http://localhost:5173/`
|
||||
|
||||
---
|
||||
|
||||
## Token Lifetimes
|
||||
|
||||
- **Access Token**: 15 minutes
|
||||
- **Refresh Token**: 7 days
|
||||
- **Session TTL**: 7 days (auto-deleted by MongoDB)
|
||||
|
||||
---
|
||||
|
||||
## Frontend Routes
|
||||
|
||||
| Route | Component | Auth Required |
|
||||
|-------|-----------|---------------|
|
||||
| `/` | HomePage | No |
|
||||
| `/market` | MarketPage | No |
|
||||
| `/item/:id` | ItemDetailsPage | No |
|
||||
| `/profile` | ProfilePage | Yes |
|
||||
| `/inventory` | InventoryPage | Yes |
|
||||
| `/sell` | SellPage | Yes |
|
||||
| `/transactions` | TransactionsPage | Yes |
|
||||
| `/deposit` | DepositPage | Yes |
|
||||
| `/withdraw` | WithdrawPage | Yes |
|
||||
| `/admin` | AdminPage | Yes (Admin only) |
|
||||
| `/faq` | FAQPage | No |
|
||||
| `/support` | SupportPage | No |
|
||||
| `/terms` | TermsPage | No |
|
||||
| `/privacy` | PrivacyPage | No |
|
||||
|
||||
---
|
||||
|
||||
## Quick Start Testing
|
||||
|
||||
1. **Start MongoDB**: `mongod`
|
||||
2. **Seed Database**: `npm run seed`
|
||||
3. **Start Backend**: `npm run dev`
|
||||
4. **Start Frontend**: `cd frontend && npm run dev`
|
||||
5. **Login**: Navigate to `http://localhost:5173` and login with Steam
|
||||
6. **Test Routes**: Use browser DevTools Network tab or curl commands above
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- All timestamps are in UTC
|
||||
- Prices are in USD
|
||||
- Image URLs may be Steam CDN or placeholder
|
||||
- WebSocket connections are optional
|
||||
- Rate limiting: 100 requests per minute (development)
|
||||
Reference in New Issue
Block a user