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)

curl "http://localhost:8000/api/v1/parks/cedar-point/"

All Rides at Park (Paginated)

# 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)

curl "http://localhost:8000/api/v1/parks/cedar-point/detail/"

Specific Ride at Park

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

{
  "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)

{
  // ... 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

{
  "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.