pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-20 05:31:09 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
1b246eeaa43f4abd52da8ac117d2df5108c565a6
thrillwiki_django_no_react/docs/THRILLWIKI_API_DOCUMENTATION.md
pacnpal 1b246eeaa4 Add comprehensive test scripts for various models and services 
- Implement tests for RideLocation and CompanyHeadquarters models to verify functionality and data integrity.
- Create a manual trigger test script for trending content calculation endpoint, including authentication and unauthorized access tests.
- Develop a manufacturer sync test to ensure ride manufacturers are correctly associated with ride models.
- Add tests for ParkLocation model, including coordinate setting and distance calculations between parks.
- Implement a RoadTripService test suite covering geocoding, route calculation, park discovery, and error handling.
- Create a unified map service test script to validate map functionality, API endpoints, and performance metrics.
2025-09-27 22:26:40 -04:00

19 KiB
Raw Blame History

ThrillWiki API Documentation v1

Complete Frontend Developer Reference

Base URL: /api/v1/
Authentication: JWT Bearer tokens
Content-Type: application/json

🔐 Authentication Endpoints (/api/v1/auth/)

Core Authentication

  • POST /auth/login/ - User login with username/email and password
  • POST /auth/signup/ - User registration (email verification required)
  • POST /auth/logout/ - Logout current user (blacklist refresh token)
  • GET /auth/user/ - Get current authenticated user information
  • POST /auth/status/ - Check authentication status

Password Management

  • POST /auth/password/reset/ - Request password reset email
  • POST /auth/password/change/ - Change current user's password

Email Verification

  • GET /auth/verify-email/<token>/ - Verify email with token
  • POST /auth/resend-verification/ - Resend email verification

Social Authentication

  • GET /auth/social/providers/ - Get available social auth providers
  • GET /auth/social/providers/available/ - Get available social providers list
  • GET /auth/social/connected/ - Get user's connected social providers
  • POST /auth/social/connect/<provider>/ - Connect social provider (Google, Discord)
  • POST /auth/social/disconnect/<provider>/ - Disconnect social provider
  • GET /auth/social/status/ - Get comprehensive social auth status
  • POST /auth/social/ - Social auth endpoints (dj-rest-auth)

JWT Token Management

  • POST /auth/token/refresh/ - Refresh JWT access token

🏞️ Parks API Endpoints (/api/v1/parks/)

Core CRUD Operations

  • GET /parks/ - List parks with comprehensive filtering and pagination
  • POST /parks/ - Create new park (authenticated users)
  • GET /parks/<pk>/ - Get park details (supports ID or slug)
  • PATCH /parks/<pk>/ - Update park (partial update)
  • PUT /parks/<pk>/ - Update park (full update)
  • DELETE /parks/<pk>/ - Delete park

Filtering & Search

  • GET /parks/filter-options/ - Get available filter options
  • GET /parks/search/companies/?q=<query> - Search companies/operators
  • GET /parks/search-suggestions/?q=<query> - Get park search suggestions
  • GET /parks/hybrid/ - Hybrid park filtering with advanced options
  • GET /parks/hybrid/filter-metadata/ - Get filter metadata for hybrid filtering

Park Photos Management

  • GET /parks/<park_pk>/photos/ - List park photos
  • POST /parks/<park_pk>/photos/ - Upload park photo
  • GET /parks/<park_pk>/photos/<id>/ - Get park photo details
  • PATCH /parks/<park_pk>/photos/<id>/ - Update park photo
  • DELETE /parks/<park_pk>/photos/<id>/ - Delete park photo
  • POST /parks/<park_pk>/photos/<id>/set_primary/ - Set photo as primary
  • POST /parks/<park_pk>/photos/bulk_approve/ - Bulk approve/reject photos (admin)
  • GET /parks/<park_pk>/photos/stats/ - Get park photo statistics

Park Settings

  • GET /parks/<pk>/image-settings/ - Get park image settings
  • POST /parks/<pk>/image-settings/ - Update park image settings

Park Filtering Parameters (24 total):

  • Pagination: page, page_size
  • Search: search
  • Location: continent, country, state, city
  • Attributes: park_type, status
  • Companies: operator_id, operator_slug, property_owner_id, property_owner_slug
  • Ratings: min_rating, max_rating
  • Ride Counts: min_ride_count, max_ride_count
  • Opening Year: opening_year, min_opening_year, max_opening_year
  • Roller Coasters: has_roller_coasters, min_roller_coaster_count, max_roller_coaster_count
  • Ordering: ordering

🎢 Rides API Endpoints (/api/v1/rides/)

Core CRUD Operations

  • GET /rides/ - List rides with comprehensive filtering
  • POST /rides/ - Create new ride
  • GET /rides/<pk>/ - Get ride details
  • PATCH /rides/<pk>/ - Update ride (partial)
  • PUT /rides/<pk>/ - Update ride (full)
  • DELETE /rides/<pk>/ - Delete ride

Filtering & Search

  • GET /rides/filter-options/ - Get available filter options
  • GET /rides/search/companies/?q=<query> - Search ride companies
  • GET /rides/search/ride-models/?q=<query> - Search ride models
  • GET /rides/search-suggestions/?q=<query> - Get ride search suggestions
  • GET /rides/hybrid/ - Hybrid ride filtering
  • GET /rides/hybrid/filter-metadata/ - Get ride filter metadata

Ride Photos Management

  • GET /rides/<ride_pk>/photos/ - List ride photos
  • POST /rides/<ride_pk>/photos/ - Upload ride photo
  • GET /rides/<ride_pk>/photos/<id>/ - Get ride photo details
  • PATCH /rides/<ride_pk>/photos/<id>/ - Update ride photo
  • DELETE /rides/<ride_pk>/photos/<id>/ - Delete ride photo
  • POST /rides/<ride_pk>/photos/<id>/set_primary/ - Set photo as primary

Ride Manufacturers

  • GET /rides/manufacturers/<manufacturer_slug>/ - Manufacturer-specific endpoints

Ride Settings

  • GET /rides/<pk>/image-settings/ - Get ride image settings
  • POST /rides/<pk>/image-settings/ - Update ride image settings

👤 User Accounts API (/api/v1/accounts/)

User Management (Admin)

  • DELETE /accounts/users/<user_id>/delete/ - Delete user while preserving submissions
  • GET /accounts/users/<user_id>/deletion-check/ - Check user deletion eligibility

Self-Service Account Management

  • POST /accounts/delete-account/request/ - Request account deletion
  • POST /accounts/delete-account/verify/ - Verify account deletion
  • POST /accounts/delete-account/cancel/ - Cancel account deletion

User Profile Management

  • GET /accounts/profile/ - Get user profile
  • PATCH /accounts/profile/account/ - Update user account info
  • PATCH /accounts/profile/update/ - Update user profile

User Preferences

  • GET /accounts/preferences/ - Get user preferences
  • PATCH /accounts/preferences/update/ - Update user preferences
  • PATCH /accounts/preferences/theme/ - Update theme preference

Settings Management

  • GET /accounts/settings/notifications/ - Get notification settings
  • PATCH /accounts/settings/notifications/update/ - Update notification settings
  • GET /accounts/settings/privacy/ - Get privacy settings
  • PATCH /accounts/settings/privacy/update/ - Update privacy settings
  • GET /accounts/settings/security/ - Get security settings
  • PATCH /accounts/settings/security/update/ - Update security settings

User Statistics & Lists

  • GET /accounts/statistics/ - Get user statistics
  • GET /accounts/top-lists/ - Get user's top lists
  • POST /accounts/top-lists/create/ - Create new top list
  • PATCH /accounts/top-lists/<list_id>/ - Update top list
  • DELETE /accounts/top-lists/<list_id>/delete/ - Delete top list

Notifications

  • GET /accounts/notifications/ - Get user notifications
  • POST /accounts/notifications/mark-read/ - Mark notifications as read
  • GET /accounts/notification-preferences/ - Get notification preferences
  • PATCH /accounts/notification-preferences/update/ - Update notification preferences

Avatar Management

  • POST /accounts/profile/avatar/upload/ - Upload avatar
  • POST /accounts/profile/avatar/save/ - Save avatar image
  • DELETE /accounts/profile/avatar/delete/ - Delete avatar

🗺️ Maps API (/api/v1/maps/)

Location Data

  • GET /maps/locations/ - Get map locations data
  • GET /maps/locations/<location_type>/<location_id>/ - Get location details
  • GET /maps/search/ - Search locations on map
  • GET /maps/bounds/ - Query locations within bounds

Map Services

  • GET /maps/stats/ - Get map service statistics
  • GET /maps/cache/ - Get map cache information
  • POST /maps/cache/invalidate/ - Invalidate map cache

🔍 Core Search API (/api/v1/core/)

Entity Search

  • GET /core/entities/search/ - Fuzzy search for entities
  • GET /core/entities/not-found/ - Handle entity not found
  • GET /core/entities/suggestions/ - Quick entity suggestions

📧 Email API (/api/v1/email/)

Email Services

  • POST /email/send/ - Send email

📜 History API (/api/v1/history/)

Park History

  • GET /history/parks/<park_slug>/ - Get park history
  • GET /history/parks/<park_slug>/detail/ - Get detailed park history

Ride History

  • GET /history/parks/<park_slug>/rides/<ride_slug>/ - Get ride history
  • GET /history/parks/<park_slug>/rides/<ride_slug>/detail/ - Get detailed ride history

Unified Timeline

  • GET /history/timeline/ - Get unified history timeline

📈 System & Analytics APIs

Health Checks

  • GET /api/v1/health/ - Comprehensive health check
  • GET /api/v1/health/simple/ - Simple health check
  • GET /api/v1/health/performance/ - Performance metrics

Trending & Discovery

  • GET /api/v1/trending/ - Get trending content
  • GET /api/v1/new-content/ - Get new content
  • POST /api/v1/trending/calculate/ - Trigger trending calculation

Statistics

  • GET /api/v1/stats/ - Get system statistics
  • POST /api/v1/stats/recalculate/ - Recalculate statistics

Reviews

  • GET /api/v1/reviews/latest/ - Get latest reviews

Rankings

  • GET /api/v1/rankings/ - Get ride rankings with filtering
  • GET /api/v1/rankings/<ride_slug>/ - Get detailed ranking for specific ride
  • GET /api/v1/rankings/<ride_slug>/history/ - Get ranking history for ride
  • GET /api/v1/rankings/<ride_slug>/comparisons/ - Get head-to-head comparisons
  • GET /api/v1/rankings/statistics/ - Get ranking system statistics
  • POST /api/v1/rankings/calculate/ - Trigger ranking calculation (admin)

Rankings Filtering Parameters:

  • category: Filter by ride category (RC, DR, FR, WR, TR, OT)
  • min_riders: Minimum number of mutual riders required
  • park: Filter by park slug
  • ordering: Order results (rank, -rank, winning_percentage, -winning_percentage)

🛡️ Moderation API (/api/v1/moderation/)

Moderation Reports

  • GET /moderation/reports/ - List all moderation reports
  • POST /moderation/reports/ - Create new moderation report
  • GET /moderation/reports/<id>/ - Get specific report details
  • PUT /moderation/reports/<id>/ - Update moderation report
  • PATCH /moderation/reports/<id>/ - Partial update report
  • DELETE /moderation/reports/<id>/ - Delete moderation report
  • POST /moderation/reports/<id>/assign/ - Assign report to moderator
  • POST /moderation/reports/<id>/resolve/ - Resolve moderation report
  • GET /moderation/reports/stats/ - Get report statistics

Moderation Queue

  • GET /moderation/queue/ - List moderation queue items
  • POST /moderation/queue/ - Create queue item
  • GET /moderation/queue/<id>/ - Get specific queue item
  • PUT /moderation/queue/<id>/ - Update queue item
  • PATCH /moderation/queue/<id>/ - Partial update queue item
  • DELETE /moderation/queue/<id>/ - Delete queue item
  • POST /moderation/queue/<id>/assign/ - Assign queue item to moderator
  • POST /moderation/queue/<id>/unassign/ - Unassign queue item
  • POST /moderation/queue/<id>/complete/ - Complete queue item
  • GET /moderation/queue/my_queue/ - Get current user's queue items

Moderation Actions

  • GET /moderation/actions/ - List all moderation actions
  • POST /moderation/actions/ - Create new moderation action
  • GET /moderation/actions/<id>/ - Get specific action details
  • PUT /moderation/actions/<id>/ - Update moderation action
  • PATCH /moderation/actions/<id>/ - Partial update action
  • DELETE /moderation/actions/<id>/ - Delete moderation action
  • POST /moderation/actions/<id>/deactivate/ - Deactivate action
  • GET /moderation/actions/active/ - Get active moderation actions
  • GET /moderation/actions/expired/ - Get expired moderation actions

Bulk Operations

  • GET /moderation/bulk-operations/ - List bulk moderation operations
  • POST /moderation/bulk-operations/ - Create bulk operation
  • GET /moderation/bulk-operations/<id>/ - Get bulk operation details
  • PUT /moderation/bulk-operations/<id>/ - Update bulk operation
  • PATCH /moderation/bulk-operations/<id>/ - Partial update operation
  • DELETE /moderation/bulk-operations/<id>/ - Delete bulk operation
  • POST /moderation/bulk-operations/<id>/cancel/ - Cancel bulk operation
  • POST /moderation/bulk-operations/<id>/retry/ - Retry failed operation
  • GET /moderation/bulk-operations/<id>/logs/ - Get operation logs
  • GET /moderation/bulk-operations/running/ - Get running operations

User Moderation

  • GET /moderation/users/<id>/ - Get user moderation profile
  • POST /moderation/users/<id>/moderate/ - Take moderation action against user
  • GET /moderation/users/search/ - Search users for moderation
  • GET /moderation/users/stats/ - Get user moderation statistics

🏗️ Ride Manufacturers & Models (/api/v1/rides/manufacturers/<manufacturer_slug>/)

Ride Models

  • GET /rides/manufacturers/<manufacturer_slug>/ - List ride models by manufacturer
  • POST /rides/manufacturers/<manufacturer_slug>/ - Create new ride model
  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/ - Get ride model details
  • PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/ - Update ride model
  • DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/ - Delete ride model

Model Search & Filtering

  • GET /rides/manufacturers/<manufacturer_slug>/search/ - Search ride models
  • GET /rides/manufacturers/<manufacturer_slug>/filter-options/ - Get filter options
  • GET /rides/manufacturers/<manufacturer_slug>/stats/ - Get manufacturer statistics

Model Variants

  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/ - List model variants
  • POST /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/ - Create variant
  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/<id>/ - Get variant details
  • PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/<id>/ - Update variant
  • DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/<id>/ - Delete variant

Technical Specifications

  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/ - List technical specs
  • POST /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/ - Create technical spec
  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/<id>/ - Get spec details
  • PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/<id>/ - Update spec
  • DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/<id>/ - Delete spec

Model Photos

  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/ - List model photos
  • POST /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/ - Upload model photo
  • GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/<id>/ - Get photo details
  • PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/<id>/ - Update photo
  • DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/<id>/ - Delete photo

🖼️ Media Management

Cloudflare Images

  • ALL /api/v1/cloudflare-images/ - Cloudflare Images toolkit endpoints

📚 API Documentation

Interactive Documentation

  • GET /api/schema/ - OpenAPI schema
  • GET /api/docs/ - Swagger UI documentation
  • GET /api/redoc/ - ReDoc documentation

🔧 Common Request/Response Patterns

Authentication Headers

headers: {
  'Authorization': 'Bearer <access_token>',
  'Content-Type': 'application/json'
}

Pagination Response

{
  "count": 100,
  "next": "http://api.example.com/api/v1/endpoint/?page=2",
  "previous": null,
  "results": [...]
}

Error Response Format

{
  "error": "Error message",
  "error_code": "SPECIFIC_ERROR_CODE",
  "details": {...},
  "suggestions": ["suggestion1", "suggestion2"]
}

Success Response Format

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {...}
}

📝 Key Data Models

User

  • id, username, email, display_name, date_joined, is_active, avatar_url

Park

  • id, name, slug, description, location, operator, park_type, status, opening_year

Ride

  • id, name, slug, park, category, manufacturer, model, opening_year, status

Photo (Park/Ride)

  • id, image, caption, photo_type, uploaded_by, is_primary, is_approved, created_at

Review

  • id, user, content_object, rating, title, content, created_at, updated_at

🚨 Important Notes

  1. Authentication Required: Most endpoints require JWT authentication
  2. Permissions: Admin endpoints require staff/superuser privileges
  3. Rate Limiting: May be implemented on certain endpoints
  4. File Uploads: Use multipart/form-data for photo uploads
  5. Pagination: Most list endpoints support pagination with page and page_size parameters
  6. Filtering: Parks and rides support extensive filtering options
  7. Cloudflare Images: Media files are handled through Cloudflare Images service
  8. Email Verification: New users must verify email before full access

📖 Usage Examples

Authentication Flow

// Login
const login = await fetch('/api/v1/auth/login/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'user@example.com', password: 'password' })
});

// Use tokens from response
const { access, refresh } = await login.json();

Fetch Parks with Filtering

const parks = await fetch('/api/v1/parks/?continent=NA&min_rating=4.0&page=1', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});

Upload Park Photo

const formData = new FormData();
formData.append('image', file);
formData.append('caption', 'Beautiful park entrance');

const photo = await fetch('/api/v1/parks/123/photos/', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${access_token}` },
  body: formData
});

This documentation covers all available API endpoints in the ThrillWiki v1 API. For detailed request/response schemas, parameter validation, and interactive testing, visit /api/docs/ when the development server is running.

Reference in New Issue View Git Blame Copy Permalink