mirror of
https://github.com/pacnpal/thrilltrack-explorer.git
synced 2025-12-20 09:11:12 -05:00
Add email templates for user notifications and account management
- Created a base email template (base.html) for consistent styling across all emails. - Added moderation approval email template (moderation_approved.html) to notify users of approved submissions. - Added moderation rejection email template (moderation_rejected.html) to inform users of required changes for their submissions. - Created password reset email template (password_reset.html) for users requesting to reset their passwords. - Developed a welcome email template (welcome.html) to greet new users and provide account details and tips for using ThrillWiki.
This commit is contained in:
pacnpal
542
django/API_GUIDE.md
Normal file
542
django/API_GUIDE.md
Normal file
@@ -0,0 +1,542 @@
|
||||
# ThrillWiki REST API Guide
|
||||
|
||||
## Phase 2B: REST API Development - Complete
|
||||
|
||||
This guide provides comprehensive documentation for the ThrillWiki REST API v1.
|
||||
|
||||
## Overview
|
||||
|
||||
The ThrillWiki API provides programmatic access to amusement park, ride, and company data. It uses django-ninja for fast, modern REST API implementation with automatic OpenAPI documentation.
|
||||
|
||||
## Base URL
|
||||
|
||||
- **Local Development**: `http://localhost:8000/api/v1/`
|
||||
- **Production**: `https://your-domain.com/api/v1/`
|
||||
|
||||
## Documentation
|
||||
|
||||
- **Interactive API Docs**: `/api/v1/docs`
|
||||
- **OpenAPI Schema**: `/api/v1/openapi.json`
|
||||
|
||||
## Features
|
||||
|
||||
### Implemented in Phase 2B
|
||||
|
||||
✅ **Full CRUD Operations** for all entities
|
||||
✅ **Filtering & Search** on all list endpoints
|
||||
✅ **Pagination** (50 items per page)
|
||||
✅ **Geographic Search** for parks (dual-mode: SQLite + PostGIS)
|
||||
✅ **Automatic OpenAPI/Swagger Documentation**
|
||||
✅ **Pydantic Schema Validation**
|
||||
✅ **Related Data** (automatic joins and annotations)
|
||||
✅ **Error Handling** with detailed error responses
|
||||
|
||||
### Coming in Phase 2C
|
||||
|
||||
- JWT Token Authentication
|
||||
- Role-based Permissions
|
||||
- Rate Limiting
|
||||
- Caching
|
||||
- Webhooks
|
||||
|
||||
## Authentication
|
||||
|
||||
**Current Status**: Authentication placeholders are in place, but not yet enforced.
|
||||
|
||||
- **Read Operations (GET)**: Public access
|
||||
- **Write Operations (POST, PUT, PATCH, DELETE)**: Will require authentication (JWT tokens)
|
||||
|
||||
## Endpoints
|
||||
|
||||
### System Endpoints
|
||||
|
||||
#### Health Check
|
||||
```
|
||||
GET /api/v1/health
|
||||
```
|
||||
Returns API health status.
|
||||
|
||||
#### API Information
|
||||
```
|
||||
GET /api/v1/info
|
||||
```
|
||||
Returns API metadata and statistics.
|
||||
|
||||
---
|
||||
|
||||
### Companies
|
||||
|
||||
Companies represent manufacturers, operators, designers, and other entities in the amusement industry.
|
||||
|
||||
#### List Companies
|
||||
```
|
||||
GET /api/v1/companies/
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (int): Page number
|
||||
- `search` (string): Search by name or description
|
||||
- `company_type` (string): Filter by type (manufacturer, operator, designer, supplier, contractor)
|
||||
- `location_id` (UUID): Filter by headquarters location
|
||||
- `ordering` (string): Sort field (prefix with `-` for descending)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/companies/?search=B%26M&ordering=-park_count"
|
||||
```
|
||||
|
||||
#### Get Company
|
||||
```
|
||||
GET /api/v1/companies/{company_id}
|
||||
```
|
||||
|
||||
#### Create Company
|
||||
```
|
||||
POST /api/v1/companies/
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Bolliger & Mabillard",
|
||||
"description": "Swiss roller coaster manufacturer",
|
||||
"company_types": ["manufacturer"],
|
||||
"founded_date": "1988-01-01",
|
||||
"website": "https://www.bolliger-mabillard.com"
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Company
|
||||
```
|
||||
PUT /api/v1/companies/{company_id}
|
||||
PATCH /api/v1/companies/{company_id}
|
||||
```
|
||||
|
||||
#### Delete Company
|
||||
```
|
||||
DELETE /api/v1/companies/{company_id}
|
||||
```
|
||||
|
||||
#### Get Company Parks
|
||||
```
|
||||
GET /api/v1/companies/{company_id}/parks
|
||||
```
|
||||
Returns all parks operated by the company.
|
||||
|
||||
#### Get Company Rides
|
||||
```
|
||||
GET /api/v1/companies/{company_id}/rides
|
||||
```
|
||||
Returns all rides manufactured by the company.
|
||||
|
||||
---
|
||||
|
||||
### Ride Models
|
||||
|
||||
Ride models represent specific ride types from manufacturers.
|
||||
|
||||
#### List Ride Models
|
||||
```
|
||||
GET /api/v1/ride-models/
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (int): Page number
|
||||
- `search` (string): Search by model name
|
||||
- `manufacturer_id` (UUID): Filter by manufacturer
|
||||
- `model_type` (string): Filter by model type
|
||||
- `ordering` (string): Sort field
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/ride-models/?manufacturer_id=<uuid>&model_type=coaster_model"
|
||||
```
|
||||
|
||||
#### Get Ride Model
|
||||
```
|
||||
GET /api/v1/ride-models/{model_id}
|
||||
```
|
||||
|
||||
#### Create Ride Model
|
||||
```
|
||||
POST /api/v1/ride-models/
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Wing Coaster",
|
||||
"manufacturer_id": "uuid-here",
|
||||
"model_type": "coaster_model",
|
||||
"description": "Winged seating roller coaster",
|
||||
"typical_height": 164.0,
|
||||
"typical_speed": 55.0
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Ride Model
|
||||
```
|
||||
PUT /api/v1/ride-models/{model_id}
|
||||
PATCH /api/v1/ride-models/{model_id}
|
||||
```
|
||||
|
||||
#### Delete Ride Model
|
||||
```
|
||||
DELETE /api/v1/ride-models/{model_id}
|
||||
```
|
||||
|
||||
#### Get Model Installations
|
||||
```
|
||||
GET /api/v1/ride-models/{model_id}/installations
|
||||
```
|
||||
Returns all rides using this model.
|
||||
|
||||
---
|
||||
|
||||
### Parks
|
||||
|
||||
Parks represent theme parks, amusement parks, water parks, and FECs.
|
||||
|
||||
#### List Parks
|
||||
```
|
||||
GET /api/v1/parks/
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (int): Page number
|
||||
- `search` (string): Search by park name
|
||||
- `park_type` (string): Filter by type (theme_park, amusement_park, water_park, family_entertainment_center, traveling_park, zoo, aquarium)
|
||||
- `status` (string): Filter by status (operating, closed, sbno, under_construction, planned)
|
||||
- `operator_id` (UUID): Filter by operator
|
||||
- `ordering` (string): Sort field
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/parks/?status=operating&park_type=theme_park"
|
||||
```
|
||||
|
||||
#### Get Park
|
||||
```
|
||||
GET /api/v1/parks/{park_id}
|
||||
```
|
||||
|
||||
#### Find Nearby Parks (Geographic Search)
|
||||
```
|
||||
GET /api/v1/parks/nearby/
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `latitude` (float, required): Center point latitude
|
||||
- `longitude` (float, required): Center point longitude
|
||||
- `radius` (float): Search radius in kilometers (default: 50)
|
||||
- `limit` (int): Maximum results (default: 50)
|
||||
|
||||
**Geographic Modes:**
|
||||
- **PostGIS (Production)**: Accurate distance-based search using `location_point`
|
||||
- **SQLite (Local Dev)**: Bounding box approximation using `latitude`/`longitude`
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/parks/nearby/?latitude=28.385233&longitude=-81.563874&radius=100"
|
||||
```
|
||||
|
||||
#### Create Park
|
||||
```
|
||||
POST /api/v1/parks/
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Six Flags Magic Mountain",
|
||||
"park_type": "theme_park",
|
||||
"status": "operating",
|
||||
"latitude": 34.4239,
|
||||
"longitude": -118.5971,
|
||||
"opening_date": "1971-05-29",
|
||||
"website": "https://www.sixflags.com/magicmountain"
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Park
|
||||
```
|
||||
PUT /api/v1/parks/{park_id}
|
||||
PATCH /api/v1/parks/{park_id}
|
||||
```
|
||||
|
||||
#### Delete Park
|
||||
```
|
||||
DELETE /api/v1/parks/{park_id}
|
||||
```
|
||||
|
||||
#### Get Park Rides
|
||||
```
|
||||
GET /api/v1/parks/{park_id}/rides
|
||||
```
|
||||
Returns all rides at the park.
|
||||
|
||||
---
|
||||
|
||||
### Rides
|
||||
|
||||
Rides represent individual rides and roller coasters.
|
||||
|
||||
#### List Rides
|
||||
```
|
||||
GET /api/v1/rides/
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (int): Page number
|
||||
- `search` (string): Search by ride name
|
||||
- `park_id` (UUID): Filter by park
|
||||
- `ride_category` (string): Filter by category (roller_coaster, flat_ride, water_ride, dark_ride, transport_ride, other)
|
||||
- `status` (string): Filter by status
|
||||
- `is_coaster` (bool): Filter for roller coasters only
|
||||
- `manufacturer_id` (UUID): Filter by manufacturer
|
||||
- `ordering` (string): Sort field
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/rides/?is_coaster=true&status=operating"
|
||||
```
|
||||
|
||||
#### List Roller Coasters Only
|
||||
```
|
||||
GET /api/v1/rides/coasters/
|
||||
```
|
||||
|
||||
**Additional Query Parameters:**
|
||||
- `min_height` (float): Minimum height in feet
|
||||
- `min_speed` (float): Minimum speed in mph
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8000/api/v1/rides/coasters/?min_height=200&min_speed=70"
|
||||
```
|
||||
|
||||
#### Get Ride
|
||||
```
|
||||
GET /api/v1/rides/{ride_id}
|
||||
```
|
||||
|
||||
#### Create Ride
|
||||
```
|
||||
POST /api/v1/rides/
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "Steel Vengeance",
|
||||
"park_id": "uuid-here",
|
||||
"ride_category": "roller_coaster",
|
||||
"is_coaster": true,
|
||||
"status": "operating",
|
||||
"manufacturer_id": "uuid-here",
|
||||
"height": 205.0,
|
||||
"speed": 74.0,
|
||||
"length": 5740.0,
|
||||
"inversions": 4,
|
||||
"opening_date": "2018-05-05"
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Ride
|
||||
```
|
||||
PUT /api/v1/rides/{ride_id}
|
||||
PATCH /api/v1/rides/{ride_id}
|
||||
```
|
||||
|
||||
#### Delete Ride
|
||||
```
|
||||
DELETE /api/v1/rides/{ride_id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Response Formats
|
||||
|
||||
### Success Responses
|
||||
|
||||
#### Single Entity
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Entity Name",
|
||||
"created": "2025-01-01T00:00:00Z",
|
||||
"modified": "2025-01-01T00:00:00Z",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
#### Paginated List
|
||||
```json
|
||||
{
|
||||
"items": [...],
|
||||
"count": 100,
|
||||
"next": "http://api/endpoint/?page=2",
|
||||
"previous": null
|
||||
}
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
|
||||
#### 400 Bad Request
|
||||
```json
|
||||
{
|
||||
"detail": "Invalid input",
|
||||
"errors": [
|
||||
{
|
||||
"field": "name",
|
||||
"message": "This field is required"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 404 Not Found
|
||||
```json
|
||||
{
|
||||
"detail": "Entity not found"
|
||||
}
|
||||
```
|
||||
|
||||
#### 500 Internal Server Error
|
||||
```json
|
||||
{
|
||||
"detail": "Internal server error",
|
||||
"code": "server_error"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Types
|
||||
|
||||
### UUID
|
||||
All entity IDs use UUID format:
|
||||
```
|
||||
"550e8400-e29b-41d4-a716-446655440000"
|
||||
```
|
||||
|
||||
### Dates
|
||||
ISO 8601 format (YYYY-MM-DD):
|
||||
```
|
||||
"2025-01-01"
|
||||
```
|
||||
|
||||
### Timestamps
|
||||
ISO 8601 format with timezone:
|
||||
```
|
||||
"2025-01-01T12:00:00Z"
|
||||
```
|
||||
|
||||
### Coordinates
|
||||
Latitude/Longitude as decimal degrees:
|
||||
```json
|
||||
{
|
||||
"latitude": 28.385233,
|
||||
"longitude": -81.563874
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing the API
|
||||
|
||||
### Using curl
|
||||
|
||||
```bash
|
||||
# Get API info
|
||||
curl http://localhost:8000/api/v1/info
|
||||
|
||||
# List companies
|
||||
curl http://localhost:8000/api/v1/companies/
|
||||
|
||||
# Search parks
|
||||
curl "http://localhost:8000/api/v1/parks/?search=Six+Flags"
|
||||
|
||||
# Find nearby parks
|
||||
curl "http://localhost:8000/api/v1/parks/nearby/?latitude=28.385&longitude=-81.563&radius=50"
|
||||
```
|
||||
|
||||
### Using the Interactive Docs
|
||||
|
||||
1. Start the development server:
|
||||
```bash
|
||||
cd django
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
2. Open your browser to:
|
||||
```
|
||||
http://localhost:8000/api/v1/docs
|
||||
```
|
||||
|
||||
3. Explore and test all endpoints interactively!
|
||||
|
||||
---
|
||||
|
||||
## Geographic Features
|
||||
|
||||
### SQLite Mode (Local Development)
|
||||
|
||||
Uses simple latitude/longitude fields with bounding box approximation:
|
||||
- Stores coordinates as `DecimalField`
|
||||
- Geographic search uses bounding box calculation
|
||||
- Less accurate but works without PostGIS
|
||||
|
||||
### PostGIS Mode (Production)
|
||||
|
||||
Uses advanced geographic features:
|
||||
- Stores coordinates as `PointField` (geography type)
|
||||
- Accurate distance-based queries
|
||||
- Supports spatial indexing
|
||||
- Full GIS capabilities
|
||||
|
||||
### Switching Between Modes
|
||||
|
||||
The API automatically detects the database backend and uses the appropriate method. No code changes needed!
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Phase 2C: Admin Interface Enhancements
|
||||
- Enhanced Django admin for all entities
|
||||
- Bulk operations
|
||||
- Advanced filtering
|
||||
- Custom actions
|
||||
|
||||
### Phase 3: Frontend Integration
|
||||
- React/Next.js frontend
|
||||
- Real-time updates
|
||||
- Interactive maps
|
||||
- Rich search interface
|
||||
|
||||
### Phase 4: Advanced Features
|
||||
- JWT authentication
|
||||
- API rate limiting
|
||||
- Caching strategies
|
||||
- Webhooks
|
||||
- WebSocket support
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about the API:
|
||||
1. Check the interactive documentation at `/api/v1/docs`
|
||||
2. Review this guide
|
||||
3. Check the POSTGIS_SETUP.md for geographic features
|
||||
4. Refer to the main README.md for project setup
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0.0** (Phase 2B): Initial REST API implementation
|
||||
- Full CRUD for all entities
|
||||
- Filtering and search
|
||||
- Geographic queries
|
||||
- Pagination
|
||||
- OpenAPI documentation
|
||||
Reference in New Issue
Block a user