pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-20 10:51:09 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
fdbbca2addc718af0808aca3d73c690dafd0d2d0
thrillwiki_django_no_react/THRILLWIKI_API_DOCUMENTATION.md
pacnpal c2c26cfd1d Add comprehensive API documentation for ThrillWiki integration and features 
- Introduced Next.js integration guide for ThrillWiki API, detailing authentication, core domain APIs, data structures, and implementation patterns.
- Documented the migration to Rich Choice Objects, highlighting changes for frontend developers and enhanced metadata availability.
- Fixed the missing `get_by_slug` method in the Ride model, ensuring proper functionality of ride detail endpoints.
- Created a test script to verify manufacturer syncing with ride models, ensuring data integrity across related models.
2025-09-16 11:29:17 -04:00

470 lines
19 KiB
Markdown
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
```javascript
headers: {
'Authorization': 'Bearer <access_token>',
'Content-Type': 'application/json'
}
```
### Pagination Response
```json
{
"count": 100,
"next": "http://api.example.com/api/v1/endpoint/?page=2",
"previous": null,
"results": [...]
}
```
### Error Response Format
```json
{
"error": "Error message",
"error_code": "SPECIFIC_ERROR_CODE",
"details": {...},
"suggestions": ["suggestion1", "suggestion2"]
}
```
### Success Response Format
```json
{
"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
```javascript
// 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
```javascript
const parks = await fetch('/api/v1/parks/?continent=NA&min_rating=4.0&page=1', {
headers: { 'Authorization': `Bearer ${access_token}` }
});
```
### Upload Park Photo
```javascript
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