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:**
```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.