thrillwiki_django_no_react/docs/README_HYBRID_ENDPOINTS.md

ThrillWiki Hybrid Filtering Endpoints Test Suite

This repository contains a comprehensive test script for the newly synchronized Parks and Rides hybrid filtering endpoints.

Quick Start

1. Start the Django server:

   cd backend && uv run manage.py runserver 8000
   

2. Run the test script:

   ./test_hybrid_endpoints.sh
   

   Or with a custom base URL:

   ./test_hybrid_endpoints.sh http://localhost:8000
   

What Gets Tested

Parks Hybrid Filtering (/api/v1/parks/hybrid/)

• ✅ Basic hybrid filtering (automatic strategy selection)
• ✅ Search functionality (?search=disney)
• ✅ Status filtering (?status=OPERATING,CLOSED_TEMP)
• ✅ Geographic filtering (?country=United%20States&state=Florida,California)
• ✅ Numeric range filtering (?opening_year_min=1990&rating_min=4.0)
• ✅ Park statistics filtering (?size_min=100&ride_count_min=10)
• ✅ Operator filtering (?operator=disney,universal)
• ✅ Progressive loading (?offset=50)
• ✅ Filter metadata (/filter-metadata/)
• ✅ Scoped metadata (/filter-metadata/?scoped=true&country=United%20States)

Rides Hybrid Filtering (/api/v1/rides/hybrid/)

• ✅ Basic hybrid filtering (automatic strategy selection)
• ✅ Search functionality (?search=coaster)
• ✅ Category filtering (?category=RC,DR)
• ✅ Status and park filtering (?status=OPERATING&park_slug=cedar-point)
• ✅ Manufacturer/designer filtering (?manufacturer=bolliger-mabillard)
• ✅ Roller coaster specific filtering (?roller_coaster_type=INVERTED&has_inversions=true)
• ✅ Performance filtering (?height_ft_min=200&speed_mph_min=70)
• ✅ Quality metrics (?rating_min=4.5&capacity_min=1000)
• ✅ Accessibility filtering (?height_requirement_min=48&height_requirement_max=54)
• ✅ Progressive loading (?offset=25&category=RC)
• ✅ Filter metadata (/filter-metadata/)
• ✅ Scoped metadata (/filter-metadata/?scoped=true&category=RC)

Advanced Testing

• ✅ Complex combination queries
• ✅ Edge cases (empty results, invalid parameters)
• ✅ Performance timing comparisons
• ✅ Error handling validation

Key Features Demonstrated

🔄 Automatic Strategy Selection

• ≤200 records: Client-side filtering (loads all data for frontend filtering)
• >200 records: Server-side filtering (database filtering with pagination)

📊 Progressive Loading

• Initial load: 50 records
• Progressive batches: 25 records
• Seamless pagination for large datasets

🔍 Comprehensive Filtering

• Parks: 17+ filter parameters including geographic, temporal, and statistical filters
• Rides: 17+ filter parameters including roller coaster specs, performance metrics, and accessibility

📋 Dynamic Filter Metadata

• Real-time filter options based on current data
• Scoped metadata for contextual filtering
• Ranges and categorical options automatically generated

⚡ Performance Optimized

• 5-minute intelligent caching
• Strategic database indexing
• Optimized queries with prefetch_related

Response Format

Both endpoints return consistent response structures:

{
  "parks": [...],           // or "rides": [...]
  "total_count": 123,
  "strategy": "client_side", // or "server_side"
  "has_more": false,
  "next_offset": null,
  "filter_metadata": {
    "categorical": {
      "countries": ["United States", "Canada", ...],
      "categories": ["RC", "DR", "FR", ...],
      // ... more options
    },
    "ranges": {
      "opening_year": {"min": 1800, "max": 2025},
      "rating": {"min": 1.0, "max": 10.0},
      // ... more ranges
    }
  }
}

Dependencies

• curl: Required for making HTTP requests
• jq: Optional but recommended for pretty JSON formatting

Example Usage

Basic Parks Query

curl "http://localhost:8000/api/v1/parks/hybrid/"

Search for Disney Parks

curl "http://localhost:8000/api/v1/parks/hybrid/?search=disney"

Filter Roller Coasters with Inversions

curl "http://localhost:8000/api/v1/rides/hybrid/?category=RC&has_inversions=true&height_ft_min=100"

Get Filter Metadata

curl "http://localhost:8000/api/v1/parks/hybrid/filter-metadata/"

Integration Guide

Frontend Integration

1. Use filter metadata to build dynamic filter interfaces
2. Implement progressive loading for better UX
3. Handle both client-side and server-side strategies
4. Cache filter metadata to reduce API calls

Performance Considerations

• Monitor response times and adjust thresholds as needed
• Use progressive loading for datasets >200 records
• Implement proper error handling for edge cases
• Consider implementing request debouncing for search

Troubleshooting

Server Not Running

❌ Server not available at http://localhost:8000
💡 Make sure to start the Django server first:
   cd backend && uv run manage.py runserver 8000

Missing jq

⚠️  jq not found - JSON responses will not be pretty-printed

Install jq for better output formatting:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

Next Steps

1. Integrate into Frontend: Use these endpoints in your React/Next.js application
2. Build Filter UI: Create dynamic filter interfaces using the metadata
3. Implement Progressive Loading: Handle large datasets efficiently
4. Monitor Performance: Track response times and optimize as needed
5. Add Caching: Implement client-side caching for better UX

---

🎢 Happy filtering! These endpoints provide a powerful, scalable foundation for building advanced search and filtering experiences in your theme park application.