thrillwiki_django_no_react/docs/rich-choice-objects-api-guide.md

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:

# 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:

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:

{
  "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:

{
  "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:

{
  "query": "Cedar Point",
  "entity_types": ["park", "ride", "company", "user"],  // Optional
  "limit": 10
}

Enhanced Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

// ✅ 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

// ✅ 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

// ✅ 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

// ✅ 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.