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:**
   ```bash
   cd backend && uv run manage.py runserver 8000
   ```

2. **Run the test script:**
   ```bash
   ./test_hybrid_endpoints.sh
   ```

   Or with a custom base URL:
   ```bash
   ./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:

```json
{
  "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
```bash
curl "http://localhost:8000/api/v1/parks/hybrid/"
```

### Search for Disney Parks
```bash
curl "http://localhost:8000/api/v1/parks/hybrid/?search=disney"
```

### Filter Roller Coasters with Inversions
```bash
curl "http://localhost:8000/api/v1/rides/hybrid/?category=RC&has_inversions=true&height_ft_min=100"
```

### Get Filter Metadata
```bash
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:
```bash
# 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.