thrillwiki_django_no_react/docs/frontend.md

# ThrillWiki Frontend API Documentation

Last updated: 2025-08-29

This document provides comprehensive documentation for all ThrillWiki API endpoints that the NextJS frontend should use.

## Authentication

All API requests require authentication via JWT tokens. Include the token in the Authorization header:

```typescript
headers: {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
}
```

## Base URL

All API endpoints are prefixed with `/api/v1/`

## Moderation System API

The moderation system provides comprehensive content moderation, user management, and administrative tools. All moderation endpoints require moderator-level permissions or above.

### Moderation Reports

#### List Reports
- **GET** `/api/v1/moderation/reports/`
- **Permissions**: Moderators and above can view all reports, regular users can only view their own reports
- **Query Parameters**:
  - `status`: Filter by report status (PENDING, UNDER_REVIEW, RESOLVED, DISMISSED)
  - `priority`: Filter by priority (LOW, MEDIUM, HIGH, URGENT)
  - `report_type`: Filter by report type (SPAM, HARASSMENT, INAPPROPRIATE_CONTENT, etc.)
  - `reported_by`: Filter by user ID who made the report
  - `assigned_moderator`: Filter by assigned moderator ID
  - `created_after`: Filter reports created after date (ISO format)
  - `created_before`: Filter reports created before date (ISO format)
  - `unassigned`: Boolean filter for unassigned reports
  - `overdue`: Boolean filter for overdue reports based on SLA
  - `search`: Search in reason and description fields
  - `ordering`: Order by fields (created_at, updated_at, priority, status)

#### Create Report
- **POST** `/api/v1/moderation/reports/`
- **Permissions**: Any authenticated user
- **Body**: CreateModerationReportData

#### Get Report Details
- **GET** `/api/v1/moderation/reports/{id}/`
- **Permissions**: Moderators and above, or report creator

#### Update Report
- **PATCH** `/api/v1/moderation/reports/{id}/`
- **Permissions**: Moderators and above
- **Body**: Partial UpdateModerationReportData

#### Assign Report
- **POST** `/api/v1/moderation/reports/{id}/assign/`
- **Permissions**: Moderators and above
- **Body**: `{ "moderator_id": number }`

#### Resolve Report
- **POST** `/api/v1/moderation/reports/{id}/resolve/`
- **Permissions**: Moderators and above
- **Body**: `{ "resolution_action": string, "resolution_notes": string }`

#### Report Statistics
- **GET** `/api/v1/moderation/reports/stats/`
- **Permissions**: Moderators and above
- **Returns**: ModerationStatsData

### Moderation Queue

#### List Queue Items
- **GET** `/api/v1/moderation/queue/`
- **Permissions**: Moderators and above
- **Query Parameters**:
  - `status`: Filter by status (PENDING, IN_PROGRESS, COMPLETED, CANCELLED)
  - `priority`: Filter by priority (LOW, MEDIUM, HIGH, URGENT)
  - `item_type`: Filter by item type (CONTENT_REVIEW, USER_REVIEW, BULK_ACTION, etc.)
  - `assigned_to`: Filter by assigned moderator ID
  - `unassigned`: Boolean filter for unassigned items
  - `has_related_report`: Boolean filter for items with related reports
  - `search`: Search in title and description fields

#### Get My Queue
- **GET** `/api/v1/moderation/queue/my_queue/`
- **Permissions**: Moderators and above
- **Returns**: Queue items assigned to current user

#### Assign Queue Item
- **POST** `/api/v1/moderation/queue/{id}/assign/`
- **Permissions**: Moderators and above
- **Body**: `{ "moderator_id": number }`

#### Unassign Queue Item
- **POST** `/api/v1/moderation/queue/{id}/unassign/`
- **Permissions**: Moderators and above

#### Complete Queue Item
- **POST** `/api/v1/moderation/queue/{id}/complete/`
- **Permissions**: Moderators and above
- **Body**: CompleteQueueItemData

### Moderation Actions

#### List Actions
- **GET** `/api/v1/moderation/actions/`
- **Permissions**: Moderators and above
- **Query Parameters**:
  - `action_type`: Filter by action type (WARNING, USER_SUSPENSION, USER_BAN, etc.)
  - `moderator`: Filter by moderator ID
  - `target_user`: Filter by target user ID
  - `is_active`: Boolean filter for active actions
  - `expired`: Boolean filter for expired actions
  - `expiring_soon`: Boolean filter for actions expiring within 24 hours
  - `has_related_report`: Boolean filter for actions with related reports

#### Create Action
- **POST** `/api/v1/moderation/actions/`
- **Permissions**: Moderators and above (with role-based restrictions)
- **Body**: CreateModerationActionData

#### Get Active Actions
- **GET** `/api/v1/moderation/actions/active/`
- **Permissions**: Moderators and above

#### Get Expired Actions
- **GET** `/api/v1/moderation/actions/expired/`
- **Permissions**: Moderators and above

#### Deactivate Action
- **POST** `/api/v1/moderation/actions/{id}/deactivate/`
- **Permissions**: Moderators and above

### Bulk Operations

#### List Bulk Operations
- **GET** `/api/v1/moderation/bulk-operations/`
- **Permissions**: Admins and superusers only
- **Query Parameters**:
  - `status`: Filter by status (PENDING, RUNNING, COMPLETED, FAILED, CANCELLED)
  - `operation_type`: Filter by operation type
  - `priority`: Filter by priority
  - `created_by`: Filter by creator ID
  - `can_cancel`: Boolean filter for cancellable operations
  - `has_failures`: Boolean filter for operations with failures
  - `in_progress`: Boolean filter for operations in progress

#### Create Bulk Operation
- **POST** `/api/v1/moderation/bulk-operations/`
- **Permissions**: Admins and superusers only
- **Body**: CreateBulkOperationData

#### Get Running Operations
- **GET** `/api/v1/moderation/bulk-operations/running/`
- **Permissions**: Admins and superusers only

#### Cancel Operation
- **POST** `/api/v1/moderation/bulk-operations/{id}/cancel/`
- **Permissions**: Admins and superusers only

#### Retry Operation
- **POST** `/api/v1/moderation/bulk-operations/{id}/retry/`
- **Permissions**: Admins and superusers only

#### Get Operation Logs
- **GET** `/api/v1/moderation/bulk-operations/{id}/logs/`
- **Permissions**: Admins and superusers only

### User Moderation

#### Get User Moderation Profile
- **GET** `/api/v1/moderation/users/{id}/`
- **Permissions**: Moderators and above
- **Returns**: UserModerationProfileData

#### Take Action Against User
- **POST** `/api/v1/moderation/users/{id}/moderate/`
- **Permissions**: Moderators and above
- **Body**: CreateModerationActionData

#### Search Users
- **GET** `/api/v1/moderation/users/search/`
- **Permissions**: Moderators and above
- **Query Parameters**:
  - `query`: Search in username and email
  - `role`: Filter by user role
  - `has_restrictions`: Boolean filter for users with active restrictions

#### User Moderation Statistics
- **GET** `/api/v1/moderation/users/stats/`
- **Permissions**: Moderators and above

## Parks API

### Parks Listing
- **GET** `/api/v1/parks/`
- **Query Parameters**:
  - `search`: Search in park names and descriptions
  - `country`: Filter by country code
  - `state`: Filter by state/province
  - `city`: Filter by city
  - `status`: Filter by operational status
  - `park_type`: Filter by park type
  - `has_rides`: Boolean filter for parks with rides
  - `ordering`: Order by fields (name, opened_date, ride_count, etc.)
  - `page`: Page number for pagination
  - `page_size`: Number of results per page

### Park Details
- **GET** `/api/v1/parks/{slug}/`
- **Returns**: Complete park information including rides, photos, and statistics

### Park Rides
- **GET** `/api/v1/parks/{park_slug}/rides/`
- **Query Parameters**: Similar filtering options as global rides endpoint

### Park Photos
- **GET** `/api/v1/parks/{park_slug}/photos/`
- **Query Parameters**:
  - `photo_type`: Filter by photo type (banner, card, gallery)
  - `ordering`: Order by upload date, likes, etc.

## Rides API

### Rides Listing
- **GET** `/api/v1/rides/`
- **Query Parameters**:
  - `search`: Search in ride names and descriptions
  - `park`: Filter by park slug
  - `manufacturer`: Filter by manufacturer slug
  - `ride_type`: Filter by ride type
  - `status`: Filter by operational status
  - `opened_after`: Filter rides opened after date
  - `opened_before`: Filter rides opened before date
  - `height_min`: Minimum height requirement
  - `height_max`: Maximum height requirement
  - `has_photos`: Boolean filter for rides with photos
  - `ordering`: Order by fields (name, opened_date, height, etc.)

### Ride Details
- **GET** `/api/v1/rides/{park_slug}/{ride_slug}/`
- **Returns**: Complete ride information including specifications, photos, and reviews

### Ride Photos
- **GET** `/api/v1/rides/{park_slug}/{ride_slug}/photos/`

### Ride Reviews
- **GET** `/api/v1/rides/{park_slug}/{ride_slug}/reviews/`
- **POST** `/api/v1/rides/{park_slug}/{ride_slug}/reviews/`

## Manufacturers API

### Manufacturers Listing
- **GET** `/api/v1/rides/manufacturers/`
- **Query Parameters**:
  - `search`: Search in manufacturer names
  - `country`: Filter by country
  - `has_rides`: Boolean filter for manufacturers with rides
  - `ordering`: Order by name, ride_count, etc.

### Manufacturer Details
- **GET** `/api/v1/rides/manufacturers/{slug}/`

### Manufacturer Rides
- **GET** `/api/v1/rides/manufacturers/{slug}/rides/`

## Authentication API

### Login
- **POST** `/api/v1/auth/login/`
- **Body**: `{ "username": string, "password": string }`
- **Returns**: JWT tokens and user data

### Signup
- **POST** `/api/v1/auth/signup/`
- **Body**: User registration data

### Logout
- **POST** `/api/v1/auth/logout/`

### Current User
- **GET** `/api/v1/auth/user/`
- **Returns**: Current user profile data

### Password Reset
- **POST** `/api/v1/auth/password/reset/`
- **Body**: `{ "email": string }`

### Password Change
- **POST** `/api/v1/auth/password/change/`
- **Body**: `{ "old_password": string, "new_password": string }`

## Statistics API

### Global Statistics
- **GET** `/api/v1/stats/`
- **Returns**: Global platform statistics

### Trending Content
- **GET** `/api/v1/trending/`
- **Query Parameters**:
  - `content_type`: Filter by content type (parks, rides, reviews)
  - `time_period`: Time period for trending (24h, 7d, 30d)

### Latest Reviews
- **GET** `/api/v1/reviews/latest/`
- **Query Parameters**:
  - `limit`: Number of reviews to return
  - `park`: Filter by park slug
  - `ride`: Filter by ride slug

## Error Handling

All API endpoints return standardized error responses:

```typescript
interface ApiError {
  status: "error";
  error: {
    code: string;
    message: string;
    details?: any;
    request_user?: string;
  };
  data: null;
}
```

Common error codes:
- `NOT_AUTHENTICATED`: User not logged in
- `PERMISSION_DENIED`: Insufficient permissions
- `NOT_FOUND`: Resource not found
- `VALIDATION_ERROR`: Invalid request data
- `RATE_LIMITED`: Too many requests

## Pagination

List endpoints use cursor-based pagination:

```typescript
interface PaginatedResponse<T> {
  status: "success";
  data: {
    results: T[];
    count: number;
    next: string | null;
    previous: string | null;
  };
  error: null;
}
```

## Rate Limiting

API endpoints are rate limited based on user role:
- Anonymous users: 100 requests/hour
- Authenticated users: 1000 requests/hour
- Moderators: 5000 requests/hour
- Admins: 10000 requests/hour

## WebSocket Connections

Real-time updates are available for:
- Moderation queue updates
- New reports and actions
- Bulk operation progress
- Live statistics updates

Connect to: `ws://localhost:8000/ws/moderation/` (requires authentication)