pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-20 08:31:08 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
b9377ead373062468190f544477b231facdd3055
thrillwiki_django_no_react/docs/rich-choice-objects-api-guide.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

11 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink