mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 05:11:09 -05:00
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.
This commit is contained in:
pacnpal
381
docs/rich-choice-objects-api-guide.md
Normal file
381
docs/rich-choice-objects-api-guide.md
Normal file
@@ -0,0 +1,381 @@
|
||||
# ThrillWiki API - Rich Choice Objects Integration Guide
|
||||
|
||||
**For Frontend Developers**
|
||||
**Date**: January 15, 2025
|
||||
**Status**: Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
The ThrillWiki API has been fully migrated from tuple-based Django choices to a comprehensive **Rich Choice Objects** system. This migration enhances API responses with richer metadata while maintaining backward compatibility for choice values.
|
||||
|
||||
## What Changed for Frontend Developers
|
||||
|
||||
### ✅ **Choice Values Remain the Same**
|
||||
All existing choice values (`"RC"`, `"OPERATING"`, `"healthy"`, etc.) remain unchanged. Your existing frontend code will continue to work without modifications.
|
||||
|
||||
**How This Works:**
|
||||
- Rich Choice Objects use the **same values** as the old tuple-based choices
|
||||
- API serializers still return the **string values** (e.g., `"OPERATING"`, not the Rich Choice Object)
|
||||
- Database storage is **unchanged** - still stores the same string values
|
||||
- The Rich Choice Objects add **metadata only** - they don't change the actual choice values
|
||||
- Django REST Framework converts Rich Choice Objects back to tuples for serialization
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# OLD: Tuple-based choice
|
||||
("OPERATING", "Operating")
|
||||
|
||||
# NEW: Rich Choice Object with same value
|
||||
RichChoice(
|
||||
value="OPERATING", # ← Same value as before
|
||||
label="Operating", # ← Same label as before
|
||||
metadata={'color': 'green', 'icon': 'check-circle'} # ← NEW metadata
|
||||
)
|
||||
|
||||
# API Response: Still returns just the value
|
||||
{"status": "OPERATING"} # ← Unchanged for frontend
|
||||
```
|
||||
|
||||
### ✅ **Enhanced Metadata Available**
|
||||
Rich Choice Objects now provide additional metadata that can enhance your UI:
|
||||
|
||||
```typescript
|
||||
interface RichChoiceMetadata {
|
||||
color: string; // e.g., "green", "red", "blue"
|
||||
icon: string; // e.g., "check-circle", "x-circle"
|
||||
css_class: string; // e.g., "bg-green-100 text-green-800"
|
||||
sort_order: number; // For consistent ordering
|
||||
http_status?: number; // For health checks
|
||||
search_weight?: number; // For search functionality
|
||||
}
|
||||
```
|
||||
|
||||
## API Endpoints with Rich Choice Objects
|
||||
|
||||
### 1. **Health Check Endpoints**
|
||||
|
||||
#### `GET /api/v1/health/`
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"status": "healthy", // "healthy" | "unhealthy"
|
||||
"timestamp": "2025-01-15T15:00:00Z",
|
||||
"version": "1.0.0",
|
||||
"environment": "production",
|
||||
"response_time_ms": 45.2,
|
||||
"checks": { /* individual check results */ },
|
||||
"metrics": { /* system metrics */ }
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /api/v1/health/simple/`
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok", // "ok" | "error"
|
||||
"timestamp": "2025-01-15T15:00:00Z",
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**Rich Choice Metadata Available:**
|
||||
- `healthy`: Green color, check-circle icon, HTTP 200
|
||||
- `unhealthy`: Red color, x-circle icon, HTTP 503
|
||||
- `ok`: Green color, check icon, HTTP 200
|
||||
- `error`: Red color, x icon, HTTP 500
|
||||
|
||||
### 2. **Search Endpoints**
|
||||
|
||||
#### `POST /api/v1/search/entities/`
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"query": "Cedar Point",
|
||||
"entity_types": ["park", "ride", "company", "user"], // Optional
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"query": "Cedar Point",
|
||||
"total_results": 5,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Cedar Point",
|
||||
"slug": "cedar-point",
|
||||
"type": "park", // Uses Rich Choice Objects
|
||||
"description": "America's Roller Coast",
|
||||
"relevance_score": 0.95,
|
||||
"context_info": { /* entity-specific data */ }
|
||||
}
|
||||
],
|
||||
"search_time_ms": 12.5
|
||||
}
|
||||
```
|
||||
|
||||
**Rich Choice Metadata Available:**
|
||||
- `park`: Green color, map-pin icon, search weight 1.0
|
||||
- `ride`: Blue color, activity icon, search weight 1.0
|
||||
- `company`: Purple color, building icon, search weight 0.8
|
||||
- `user`: Orange color, user icon, search weight 0.5
|
||||
|
||||
### 3. **Rides Endpoints**
|
||||
|
||||
#### `GET /api/v1/rides/`
|
||||
#### `GET /api/v1/parks/{park_slug}/rides/`
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Steel Vengeance",
|
||||
"slug": "steel-vengeance",
|
||||
"category": "RC", // Rich Choice Object value
|
||||
"status": "OPERATING", // Rich Choice Object value
|
||||
"description": "Hybrid roller coaster",
|
||||
"park": { /* park info */ },
|
||||
"average_rating": 4.8,
|
||||
"capacity_per_hour": 1200,
|
||||
"opening_date": "2018-05-05"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Rich Choice Metadata Available:**
|
||||
|
||||
**Categories:**
|
||||
- `RC`: "Roller Coaster" - Red color, roller-coaster icon
|
||||
- `DR`: "Dark Ride" - Purple color, dark-ride icon
|
||||
- `FR`: "Flat Ride" - Blue color, flat-ride icon
|
||||
- `WR`: "Water Ride" - Cyan color, water-ride icon
|
||||
- `TR`: "Transport Ride" - Green color, transport icon
|
||||
- `OT`: "Other" - Gray color, other icon
|
||||
|
||||
**Statuses:**
|
||||
- `OPERATING`: "Operating" - Green color, check-circle icon
|
||||
- `CLOSED_TEMP`: "Temporarily Closed" - Yellow color, pause-circle icon
|
||||
- `SBNO`: "Standing But Not Operating" - Orange color, stop-circle icon
|
||||
- `CLOSING`: "Closing" - Red color, x-circle icon
|
||||
- `CLOSED_PERM`: "Permanently Closed" - Red color, x-circle icon
|
||||
- `UNDER_CONSTRUCTION`: "Under Construction" - Blue color, tool icon
|
||||
- `DEMOLISHED`: "Demolished" - Gray color, trash icon
|
||||
- `RELOCATED`: "Relocated" - Purple color, arrow-right icon
|
||||
|
||||
#### `POST /api/v1/rides/`
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "New Coaster",
|
||||
"description": "Amazing new ride",
|
||||
"category": "RC", // Must use Rich Choice Object values
|
||||
"status": "UNDER_CONSTRUCTION", // Must use Rich Choice Object values
|
||||
"park_id": 1,
|
||||
"opening_date": "2025-06-01"
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /api/v1/rides/{ride_id}/`
|
||||
**Enhanced Response includes all Rich Choice Object values for:**
|
||||
- `category`: Ride category classification
|
||||
- `status`: Current operational status
|
||||
- `post_closing_status`: Status after closure (if applicable)
|
||||
|
||||
### 4. **Roller Coaster Statistics**
|
||||
|
||||
#### `GET /api/v1/rides/{ride_id}/stats/`
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"height_ft": 205.0,
|
||||
"length_ft": 5740.0,
|
||||
"speed_mph": 74.0,
|
||||
"inversions": 4,
|
||||
"track_material": "HYBRID", // Rich Choice Object value
|
||||
"roller_coaster_type": "SITDOWN", // Rich Choice Object value
|
||||
"launch_type": "CHAIN", // Rich Choice Object value
|
||||
"ride": { /* ride info */ }
|
||||
}
|
||||
```
|
||||
|
||||
**Rich Choice Metadata Available:**
|
||||
|
||||
**Track Materials:**
|
||||
- `STEEL`: "Steel" - Gray color, steel icon
|
||||
- `WOOD`: "Wood" - Amber color, wood icon
|
||||
- `HYBRID`: "Hybrid" - Orange color, hybrid icon
|
||||
|
||||
**Coaster Types:**
|
||||
- `SITDOWN`: "Sit Down" - Blue color, sitdown icon
|
||||
- `INVERTED`: "Inverted" - Purple color, inverted icon
|
||||
- `FLYING`: "Flying" - Sky color, flying icon
|
||||
- `STANDUP`: "Stand Up" - Green color, standup icon
|
||||
- `WING`: "Wing" - Indigo color, wing icon
|
||||
- `DIVE`: "Dive" - Red color, dive icon
|
||||
- And more...
|
||||
|
||||
**Launch Systems:**
|
||||
- `CHAIN`: "Chain Lift" - Gray color, chain icon
|
||||
- `LSM`: "LSM Launch" - Blue color, lightning icon
|
||||
- `HYDRAULIC`: "Hydraulic Launch" - Red color, hydraulic icon
|
||||
- `GRAVITY`: "Gravity" - Green color, gravity icon
|
||||
- `OTHER`: "Other" - Gray color, other icon
|
||||
|
||||
### 5. **Parks Endpoints**
|
||||
|
||||
#### `GET /api/v1/parks/`
|
||||
#### `GET /api/v1/parks/{park_slug}/`
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Cedar Point",
|
||||
"slug": "cedar-point",
|
||||
"status": "OPERATING", // Rich Choice Object value
|
||||
"description": "America's Roller Coast",
|
||||
"location": { /* location info */ }
|
||||
}
|
||||
```
|
||||
|
||||
**Park Status Rich Choice Metadata Available:**
|
||||
- Similar to ride statuses but park-specific
|
||||
|
||||
### 6. **Company Endpoints**
|
||||
|
||||
#### `GET /api/v1/companies/`
|
||||
**Enhanced Response:**
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Rocky Mountain Construction",
|
||||
"slug": "rocky-mountain-construction",
|
||||
"roles": ["MANUFACTURER"] // Rich Choice Object values
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Company Role Rich Choice Metadata Available:**
|
||||
|
||||
**Rides Domain:**
|
||||
- `MANUFACTURER`: "Ride Manufacturer" - Blue color, factory icon
|
||||
- `DESIGNER`: "Ride Designer" - Purple color, design icon
|
||||
|
||||
**Parks Domain:**
|
||||
- `OPERATOR`: "Park Operator" - Green color, operator icon
|
||||
- `PROPERTY_OWNER`: "Property Owner" - Orange color, property icon
|
||||
|
||||
## Frontend Implementation Guidelines
|
||||
|
||||
### 1. **Choice Value Handling**
|
||||
```typescript
|
||||
// ✅ Continue using existing choice values
|
||||
const rideStatus = "OPERATING";
|
||||
const rideCategory = "RC";
|
||||
const healthStatus = "healthy";
|
||||
|
||||
// ✅ Values remain the same, no changes needed
|
||||
if (ride.status === "OPERATING") {
|
||||
// Your existing logic works unchanged
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **Enhanced UI with Rich Metadata**
|
||||
```typescript
|
||||
// ✅ Optional: Enhance UI with Rich Choice metadata
|
||||
interface RideStatusDisplay {
|
||||
value: string;
|
||||
label: string;
|
||||
color: string;
|
||||
icon: string;
|
||||
cssClass: string;
|
||||
}
|
||||
|
||||
// You can request metadata from a new endpoint (if implemented)
|
||||
// or use static mappings based on the documentation above
|
||||
const statusDisplay: Record<string, RideStatusDisplay> = {
|
||||
"OPERATING": {
|
||||
value: "OPERATING",
|
||||
label: "Operating",
|
||||
color: "green",
|
||||
icon: "check-circle",
|
||||
cssClass: "bg-green-100 text-green-800"
|
||||
},
|
||||
"CLOSED_TEMP": {
|
||||
value: "CLOSED_TEMP",
|
||||
label: "Temporarily Closed",
|
||||
color: "yellow",
|
||||
icon: "pause-circle",
|
||||
cssClass: "bg-yellow-100 text-yellow-800"
|
||||
}
|
||||
// ... more statuses
|
||||
};
|
||||
```
|
||||
|
||||
### 3. **Form Validation**
|
||||
```typescript
|
||||
// ✅ Use the same choice values for form validation
|
||||
const validRideCategories = ["RC", "DR", "FR", "WR", "TR", "OT"];
|
||||
const validRideStatuses = ["OPERATING", "CLOSED_TEMP", "SBNO", "CLOSING", "CLOSED_PERM", "UNDER_CONSTRUCTION", "DEMOLISHED", "RELOCATED"];
|
||||
const validHealthStatuses = ["healthy", "unhealthy"];
|
||||
const validSimpleHealthStatuses = ["ok", "error"];
|
||||
const validEntityTypes = ["park", "ride", "company", "user"];
|
||||
```
|
||||
|
||||
### 4. **Error Handling**
|
||||
```typescript
|
||||
// ✅ Enhanced error responses maintain same structure
|
||||
interface ApiError {
|
||||
status: "error";
|
||||
error: {
|
||||
code: string;
|
||||
message: string;
|
||||
details?: any;
|
||||
};
|
||||
data: null;
|
||||
}
|
||||
```
|
||||
|
||||
## Migration Impact Summary
|
||||
|
||||
### ✅ **No Breaking Changes**
|
||||
- All existing choice values remain the same
|
||||
- API response structures unchanged
|
||||
- Existing frontend code continues to work
|
||||
|
||||
### ✅ **Enhanced Capabilities**
|
||||
- Richer metadata available for UI enhancements
|
||||
- Consistent color schemes and icons across domains
|
||||
- Better sorting and categorization support
|
||||
- Enhanced search functionality with entity type weighting
|
||||
|
||||
### ✅ **Improved Developer Experience**
|
||||
- More descriptive choice labels
|
||||
- Consistent metadata structure across all domains
|
||||
- Better API documentation with rich choice information
|
||||
- Type-safe choice handling
|
||||
|
||||
## Next Steps for Frontend Development
|
||||
|
||||
1. **Continue using existing choice values** - No immediate changes required
|
||||
2. **Optionally enhance UI** with rich metadata for better user experience
|
||||
3. **Consider implementing** color-coded status indicators using the provided metadata
|
||||
4. **Update TypeScript types** to include rich choice metadata if desired
|
||||
5. **Test thoroughly** - All existing functionality should work unchanged
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter any issues with the Rich Choice Objects migration or need clarification on any API endpoints, please refer to:
|
||||
|
||||
- **API Documentation**: `/api/v1/schema/` (OpenAPI/Swagger)
|
||||
- **Django Admin**: Rich Choice Objects are visible in admin interface
|
||||
- **System Health**: `/api/v1/health/` endpoint for system status
|
||||
|
||||
The migration is **production-ready** and **fully backward compatible**. Your existing frontend code will continue to work without any modifications while providing the foundation for enhanced UI capabilities.
|
||||
Reference in New Issue
Block a user