Tonne of debugging - getting ready for the production builds
This commit is contained in:
383
mkdocs/docs/v2/api-reference/index.md
Normal file
383
mkdocs/docs/v2/api-reference/index.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# API Reference
|
||||
|
||||
Complete REST API reference for Changemaker Lite V2. This section documents all API endpoints, request/response formats, authentication, and error handling.
|
||||
|
||||
## Overview
|
||||
|
||||
Changemaker Lite V2 provides two REST APIs:
|
||||
|
||||
- **Express API** (Port 4000) - Main application API
|
||||
- **Fastify Media API** (Port 4100) - Media library operations
|
||||
|
||||
Both APIs use JSON for request/response bodies and follow RESTful conventions.
|
||||
|
||||
## API Documentation
|
||||
|
||||
API reference documentation will be added as the API stabilizes. Planned documentation includes:
|
||||
|
||||
### Authentication Endpoints
|
||||
|
||||
- `POST /api/auth/register` - User registration
|
||||
- `POST /api/auth/login` - User login
|
||||
- `POST /api/auth/refresh` - Refresh access token
|
||||
- `POST /api/auth/logout` - User logout
|
||||
- `GET /api/auth/me` - Get current user
|
||||
|
||||
### User Endpoints
|
||||
|
||||
- `GET /api/users` - List users
|
||||
- `POST /api/users` - Create user
|
||||
- `GET /api/users/:id` - Get user
|
||||
- `PATCH /api/users/:id` - Update user
|
||||
- `DELETE /api/users/:id` - Delete user
|
||||
|
||||
### Campaign Endpoints
|
||||
|
||||
- `GET /api/campaigns` - List campaigns
|
||||
- `POST /api/campaigns` - Create campaign
|
||||
- `GET /api/campaigns/:id` - Get campaign
|
||||
- `PATCH /api/campaigns/:id` - Update campaign
|
||||
- `DELETE /api/campaigns/:id` - Delete campaign
|
||||
- `GET /api/campaigns/public` - List public campaigns
|
||||
- `POST /api/campaigns/:id/send-email` - Send campaign email
|
||||
|
||||
### Location Endpoints
|
||||
|
||||
- `GET /api/locations` - List locations
|
||||
- `POST /api/locations` - Create location
|
||||
- `GET /api/locations/:id` - Get location
|
||||
- `PATCH /api/locations/:id` - Update location
|
||||
- `DELETE /api/locations/:id` - Delete location
|
||||
- `POST /api/locations/import` - CSV import
|
||||
- `GET /api/locations/export` - CSV export
|
||||
- `POST /api/locations/geocode` - Bulk geocode
|
||||
|
||||
### Map Endpoints
|
||||
|
||||
- `GET /api/cuts` - List cuts
|
||||
- `POST /api/cuts` - Create cut
|
||||
- `GET /api/shifts` - List shifts
|
||||
- `POST /api/shifts` - Create shift
|
||||
- `GET /api/canvass/session` - Get active session
|
||||
- `POST /api/canvass/session/start` - Start session
|
||||
- `POST /api/canvass/visit` - Record visit
|
||||
|
||||
### Content Endpoints
|
||||
|
||||
- `GET /api/pages` - List pages
|
||||
- `POST /api/pages` - Create page
|
||||
- `GET /api/pages/public/:slug` - Get published page
|
||||
- `GET /api/email-templates` - List templates
|
||||
- `POST /api/email-templates` - Create template
|
||||
|
||||
### Media Endpoints (Port 4100)
|
||||
|
||||
- `GET /media-api/videos` - List videos
|
||||
- `POST /media-api/upload` - Upload video
|
||||
- `GET /media-api/public/videos` - List public videos
|
||||
- `POST /media-api/reactions` - Add reaction
|
||||
|
||||
## Authentication
|
||||
|
||||
All authenticated endpoints require a valid JWT access token in the Authorization header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
### Token Lifecycle
|
||||
|
||||
1. **Login** - POST `/api/auth/login`
|
||||
- Returns: `accessToken` (15min) + `refreshToken` (7 days)
|
||||
|
||||
2. **Access Protected Resource** - Include token in header
|
||||
- Token verified by `authenticate` middleware
|
||||
|
||||
3. **Refresh Token** - POST `/api/auth/refresh`
|
||||
- Provide: `refreshToken`
|
||||
- Returns: New `accessToken` + `refreshToken`
|
||||
|
||||
4. **Logout** - POST `/api/auth/logout`
|
||||
- Invalidates refresh token
|
||||
|
||||
### Role-Based Access
|
||||
|
||||
Endpoints are protected by role requirements:
|
||||
|
||||
- **Public** - No authentication required
|
||||
- **Authenticated** - Any logged-in user
|
||||
- **Admin** - SUPER_ADMIN, INFLUENCE_ADMIN, or MAP_ADMIN
|
||||
- **Role-Specific** - Specific role required
|
||||
|
||||
## Request Format
|
||||
|
||||
### JSON Body
|
||||
|
||||
```json
|
||||
POST /api/campaigns
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <token>
|
||||
|
||||
{
|
||||
"name": "Save the Parks",
|
||||
"description": "Campaign description",
|
||||
"published": true
|
||||
}
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
```
|
||||
GET /api/campaigns?page=1&limit=20&search=parks
|
||||
```
|
||||
|
||||
### Path Parameters
|
||||
|
||||
```
|
||||
GET /api/campaigns/:id
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Success Response
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Save the Parks",
|
||||
"description": "Campaign description",
|
||||
"published": true,
|
||||
"createdAt": "2026-01-01T00:00:00.000Z",
|
||||
"updatedAt": "2026-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Paginated Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100,
|
||||
"totalPages": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Validation error",
|
||||
"details": "Invalid email format",
|
||||
"statusCode": 400
|
||||
}
|
||||
```
|
||||
|
||||
## Status Codes
|
||||
|
||||
- **200 OK** - Success
|
||||
- **201 Created** - Resource created
|
||||
- **204 No Content** - Success with no body
|
||||
- **400 Bad Request** - Validation error
|
||||
- **401 Unauthorized** - Authentication required
|
||||
- **403 Forbidden** - Insufficient permissions
|
||||
- **404 Not Found** - Resource not found
|
||||
- **429 Too Many Requests** - Rate limit exceeded
|
||||
- **500 Internal Server Error** - Server error
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Rate limits vary by endpoint:
|
||||
|
||||
- **Auth endpoints** - 10 requests/minute per IP
|
||||
- **Canvass visits** - 30 requests/minute per IP
|
||||
- **Public endpoints** - 60 requests/minute per IP
|
||||
- **Authenticated endpoints** - 120 requests/minute per user
|
||||
|
||||
Rate limit headers:
|
||||
|
||||
```
|
||||
X-RateLimit-Limit: 60
|
||||
X-RateLimit-Remaining: 59
|
||||
X-RateLimit-Reset: 1640995200
|
||||
```
|
||||
|
||||
## CORS
|
||||
|
||||
CORS is enabled for all origins in development:
|
||||
|
||||
```javascript
|
||||
app.use(cors({
|
||||
origin: '*',
|
||||
credentials: true,
|
||||
}));
|
||||
```
|
||||
|
||||
Production should restrict to known domains.
|
||||
|
||||
## Validation
|
||||
|
||||
Request bodies are validated using Zod schemas. Validation errors return 400 with details:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Validation error",
|
||||
"details": {
|
||||
"email": "Invalid email format",
|
||||
"password": "Password must be at least 12 characters"
|
||||
},
|
||||
"statusCode": 400
|
||||
}
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
List endpoints support pagination:
|
||||
|
||||
- **page** - Page number (default: 1)
|
||||
- **limit** - Items per page (default: 20, max: 100)
|
||||
|
||||
Example:
|
||||
```
|
||||
GET /api/campaigns?page=2&limit=50
|
||||
```
|
||||
|
||||
## Search & Filtering
|
||||
|
||||
List endpoints support search and filtering:
|
||||
|
||||
- **search** - Text search (varies by endpoint)
|
||||
- **filter** - Field-specific filters
|
||||
|
||||
Example:
|
||||
```
|
||||
GET /api/campaigns?search=parks&published=true
|
||||
```
|
||||
|
||||
## Sorting
|
||||
|
||||
List endpoints support sorting:
|
||||
|
||||
- **sort** - Field to sort by
|
||||
- **order** - Sort direction (asc/desc)
|
||||
|
||||
Example:
|
||||
```
|
||||
GET /api/campaigns?sort=createdAt&order=desc
|
||||
```
|
||||
|
||||
## API Endpoints by Module
|
||||
|
||||
### Authentication
|
||||
- Login, register, refresh, logout, current user
|
||||
|
||||
### Users
|
||||
- CRUD operations, pagination, search, role management
|
||||
|
||||
### Settings
|
||||
- Site settings singleton
|
||||
|
||||
### Campaigns
|
||||
- CRUD, public listing, email sending
|
||||
|
||||
### Representatives
|
||||
- Postal code lookup, cache management
|
||||
|
||||
### Responses
|
||||
- CRUD, verification, upvoting, moderation
|
||||
|
||||
### Postal Codes
|
||||
- Cache service
|
||||
|
||||
### Campaign Emails
|
||||
- Email tracking, statistics
|
||||
|
||||
### Email Queue
|
||||
- Queue monitoring, pause/resume, cleanup
|
||||
|
||||
### Locations
|
||||
- CRUD, CSV import/export, geocoding, NAR import
|
||||
|
||||
### Cuts
|
||||
- CRUD, spatial queries, location assignment
|
||||
|
||||
### Shifts
|
||||
- CRUD, signups, email notifications
|
||||
|
||||
### Canvass
|
||||
- Sessions, visits, routes, dashboard
|
||||
|
||||
### Tracking
|
||||
- GPS tracking (future)
|
||||
|
||||
### Map Settings
|
||||
- Map configuration
|
||||
|
||||
### Pages
|
||||
- CRUD, block library, MkDocs export, public rendering
|
||||
|
||||
### Email Templates
|
||||
- CRUD, versioning (future)
|
||||
|
||||
### Media (Port 4100)
|
||||
- Videos, upload, shared media, reactions, jobs
|
||||
|
||||
### Listmonk
|
||||
- Status, sync, test connection
|
||||
|
||||
### Pangolin
|
||||
- Tunnel management, setup, configuration
|
||||
|
||||
### Docs
|
||||
- MkDocs/Code Server status
|
||||
|
||||
### QR
|
||||
- QR code generation
|
||||
|
||||
### Observability
|
||||
- Prometheus/Grafana/Alertmanager integration
|
||||
|
||||
### Services
|
||||
- Health checks
|
||||
|
||||
## OpenAPI Specification
|
||||
|
||||
OpenAPI/Swagger documentation is planned for future releases. This will provide:
|
||||
|
||||
- Interactive API explorer
|
||||
- Auto-generated client libraries
|
||||
- Comprehensive endpoint documentation
|
||||
- Request/response examples
|
||||
|
||||
## Testing
|
||||
|
||||
Test API endpoints using:
|
||||
|
||||
- **curl** - Command-line HTTP client
|
||||
- **Postman** - GUI API client
|
||||
- **HTTPie** - User-friendly CLI
|
||||
- **Insomnia** - API design/testing tool
|
||||
|
||||
Example with curl:
|
||||
|
||||
```bash
|
||||
# Login
|
||||
curl -X POST http://localhost:4000/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"admin@example.com","password":"Admin123!"}'
|
||||
|
||||
# Get campaigns (with token)
|
||||
curl http://localhost:4000/api/campaigns \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Backend Modules](../backend/modules/index.md)
|
||||
- [Authentication](../backend/modules/auth.md)
|
||||
- [Middleware](../backend/middleware/index.md)
|
||||
- [Development Guide](../development/index.md)
|
||||
- [Troubleshooting](../troubleshooting/index.md)
|
||||
Reference in New Issue
Block a user