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:

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:

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:

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)