thrillwiki_django_no_react/docs/park-detail-endpoint-documentation.md

# Park Detail Endpoints Documentation

## Overview

The ThrillWiki API provides multiple endpoints for accessing park information with different levels of detail and functionality.

## Available Endpoints

### 1. Basic Park Detail
**Endpoint:** `GET /api/v1/parks/{park-slug}/`
**Purpose:** Fast loading of core park information

**Response includes:**
- Basic park details (name, slug, status, description)
- Location information with coordinates
- Operator and property owner details
- Park statistics (ride count, coaster count, average rating)
- Park areas/themed sections
- Photo information (primary, banner, card images)
- **Does NOT include individual ride details**

### 2. Park Rides List (Paginated)
**Endpoint:** `GET /api/v1/parks/{park-slug}/rides/`
**Purpose:** Paginated list of all rides at a specific park

**Query Parameters:**
- `page` - Page number for pagination
- `page_size` - Number of results per page (max 100, default 20)
- `category` - Filter by ride category (RC, FR, WR, etc.)
- `status` - Filter by operational status
- `search` - Search rides by name or description
- `ordering` - Order results by field

**Response includes:**
- Paginated list of rides with full details
- Each ride includes: name, slug, category, status, manufacturer, ratings, capacity, dates
- Pagination metadata (count, next, previous)

### 3. Individual Park Ride Detail
**Endpoint:** `GET /api/v1/parks/{park-slug}/rides/{ride-slug}/`
**Purpose:** Comprehensive details for a specific ride within park context

**Response includes:**
- Complete ride information
- Park context information
- Manufacturer and designer details
- Technical specifications
- Photos and media

### 4. Comprehensive Park Detail (RESTORED)
**Endpoint:** `GET /api/v1/parks/{park-slug}/detail/`
**Purpose:** Complete park information with rides summary

**Response includes:**
- All basic park detail information
- **Plus:** `rides_summary` object containing:
  - `total_count` - Total number of rides at the park
  - `sample` - First 10 rides with full details
  - `full_list_url` - Link to paginated rides endpoint

## Usage Examples

### Basic Park Info (Fast Loading)
```bash
curl "http://localhost:8000/api/v1/parks/cedar-point/"
```

### All Rides at Park (Paginated)
```bash
# First page
curl "http://localhost:8000/api/v1/parks/cedar-point/rides/"

# With filtering
curl "http://localhost:8000/api/v1/parks/cedar-point/rides/?category=RC&status=OPERATING"

# With pagination
curl "http://localhost:8000/api/v1/parks/cedar-point/rides/?page=2&page_size=10"
```

### Comprehensive Park Detail (With Rides Summary)
```bash
curl "http://localhost:8000/api/v1/parks/cedar-point/detail/"
```

### Specific Ride at Park
```bash
curl "http://localhost:8000/api/v1/parks/cedar-point/rides/millennium-force/"
```

## Frontend Implementation Strategy

### Recommended Approach
1. **Initial Page Load:** Use `/parks/{slug}/` for fast park header/info
2. **Progressive Enhancement:** Load rides via `/parks/{slug}/rides/` with pagination
3. **Alternative:** Use `/parks/{slug}/detail/` for single-request comprehensive data

### Performance Considerations
- Basic park detail: ~2KB response, very fast
- Rides list: ~20KB per page (20 rides), paginated
- Comprehensive detail: ~25KB response, includes rides sample

### Caching Strategy
- Basic park data: Long cache (park info changes rarely)
- Rides data: Medium cache (ride status may change)
- Comprehensive detail: Medium cache (combines both)

## Response Structure Examples

### Basic Park Detail Response
```json
{
  "id": 249,
  "name": "Cedar Point",
  "slug": "cedar-point",
  "status": "OPERATING",
  "description": "Roller coaster capital of the world",
  "location": {
    "city": "Sandusky",
    "state": "OH",
    "country": "USA",
    "latitude": 41.4814,
    "longitude": -82.6838
  },
  "operator": {
    "id": 339,
    "name": "Cedar Fair",
    "slug": "cedar-fair"
  },
  "ride_count": 4,
  "coaster_count": 0,
  "average_rating": "8.16"
}
```

### Comprehensive Detail Response (Additional Fields)
```json
{
  // ... all basic park fields ...
  "rides_summary": {
    "total_count": 4,
    "sample": [
      {
        "id": 591,
        "name": "Cyclone",
        "slug": "cyclone",
        "category": "FR",
        "status": "OPERATING",
        "average_rating": "8.91"
      }
      // ... up to 10 rides
    ],
    "full_list_url": "/api/v1/parks/cedar-point/rides/"
  }
}
```

### Paginated Rides Response
```json
{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 591,
      "name": "Cyclone",
      "slug": "cyclone",
      "category": "FR",
      "status": "OPERATING",
      "description": "Exciting FR ride with thrilling elements",
      "park": {
        "id": 249,
        "name": "Cedar Point",
        "slug": "cedar-point"
      },
      "average_rating": "8.91",
      "capacity_per_hour": 1359,
      "opening_date": "1999-10-10"
    }
    // ... more rides
  ]
}
```

## Historical Context

The `/detail/` endpoint was temporarily removed during API refactoring but has been restored based on user feedback. It provides a middle-ground solution between the basic park endpoint and separate rides pagination, offering comprehensive park data with a rides preview in a single request.