mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 13:31:08 -05:00
Add comprehensive system architecture and feature documentation for ThrillWiki
This commit is contained in:
pacnpal
410
memory-bank/documentation/APIs.md
Normal file
410
memory-bank/documentation/APIs.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# API Documentation
|
||||
|
||||
## API Overview
|
||||
|
||||
### Base Configuration
|
||||
```python
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_AUTHENTICATION_CLASSES': [
|
||||
'rest_framework_jwt.authentication.JSONWebTokenAuthentication',
|
||||
'rest_framework.authentication.SessionAuthentication',
|
||||
],
|
||||
'DEFAULT_PERMISSION_CLASSES': [
|
||||
'rest_framework.permissions.IsAuthenticated',
|
||||
],
|
||||
'DEFAULT_PAGINATION_CLASS':
|
||||
'rest_framework.pagination.PageNumberPagination',
|
||||
'PAGE_SIZE': 20,
|
||||
'DEFAULT_VERSIONING_CLASS':
|
||||
'rest_framework.versioning.AcceptHeaderVersioning',
|
||||
'DEFAULT_VERSION': 'v1'
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### JWT Authentication
|
||||
```http
|
||||
POST /api/token/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "user@example.com",
|
||||
"[PASSWORD-REMOVED]"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
||||
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
|
||||
}
|
||||
```
|
||||
|
||||
### Token Refresh
|
||||
```http
|
||||
POST /api/token/refresh/
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"access": "eyJ0eXAiOiJKV1QiLCJhbGc..."
|
||||
}
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Parks API
|
||||
|
||||
#### List Parks
|
||||
```http
|
||||
GET /api/v1/parks/
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response:
|
||||
{
|
||||
"count": 100,
|
||||
"next": "http://api.thrillwiki.com/parks/?page=2",
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Adventure Park",
|
||||
"slug": "adventure-park",
|
||||
"status": "OPERATING",
|
||||
"description": "...",
|
||||
"location": {
|
||||
"city": "Orlando",
|
||||
"state": "FL",
|
||||
"country": "USA"
|
||||
},
|
||||
"ride_count": 25,
|
||||
"average_rating": 4.5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Park Detail
|
||||
```http
|
||||
GET /api/v1/parks/{slug}/
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Adventure Park",
|
||||
"slug": "adventure-park",
|
||||
"status": "OPERATING",
|
||||
"description": "...",
|
||||
"location": {
|
||||
"address": "123 Theme Park Way",
|
||||
"city": "Orlando",
|
||||
"state": "FL",
|
||||
"country": "USA",
|
||||
"postal_code": "32819",
|
||||
"coordinates": {
|
||||
"latitude": 28.538336,
|
||||
"longitude": -81.379234
|
||||
}
|
||||
},
|
||||
"owner": {
|
||||
"id": 1,
|
||||
"name": "Theme Park Corp",
|
||||
"verified": true
|
||||
},
|
||||
"stats": {
|
||||
"ride_count": 25,
|
||||
"coaster_count": 5,
|
||||
"average_rating": 4.5
|
||||
},
|
||||
"rides": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Thrill Coaster",
|
||||
"type": "ROLLER_COASTER",
|
||||
"status": "OPERATING"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Rides API
|
||||
|
||||
#### List Rides
|
||||
```http
|
||||
GET /api/v1/parks/{park_slug}/rides/
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response:
|
||||
{
|
||||
"count": 25,
|
||||
"next": null,
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Thrill Coaster",
|
||||
"slug": "thrill-coaster",
|
||||
"type": "ROLLER_COASTER",
|
||||
"status": "OPERATING",
|
||||
"height_requirement": 48,
|
||||
"thrill_rating": 5,
|
||||
"manufacturer": {
|
||||
"id": 1,
|
||||
"name": "Coaster Corp"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Ride Detail
|
||||
```http
|
||||
GET /api/v1/rides/{ride_slug}/
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Thrill Coaster",
|
||||
"slug": "thrill-coaster",
|
||||
"type": "ROLLER_COASTER",
|
||||
"status": "OPERATING",
|
||||
"description": "...",
|
||||
"specifications": {
|
||||
"height_requirement": 48,
|
||||
"thrill_rating": 5,
|
||||
"capacity_per_hour": 1200,
|
||||
"track_length": 3000
|
||||
},
|
||||
"manufacturer": {
|
||||
"id": 1,
|
||||
"name": "Coaster Corp"
|
||||
},
|
||||
"designer": {
|
||||
"id": 1,
|
||||
"name": "John Designer"
|
||||
},
|
||||
"opening_date": "2020-06-15",
|
||||
"stats": {
|
||||
"average_rating": 4.8,
|
||||
"review_count": 150
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Reviews API
|
||||
|
||||
#### Create Review
|
||||
```http
|
||||
POST /api/v1/reviews/
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"content_type": "ride",
|
||||
"object_id": 1,
|
||||
"rating": 5,
|
||||
"content": "Amazing experience!",
|
||||
"media": [
|
||||
{
|
||||
"type": "image",
|
||||
"file": "base64encoded..."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": 1,
|
||||
"author": {
|
||||
"id": 1,
|
||||
"username": "reviewer"
|
||||
},
|
||||
"rating": 5,
|
||||
"content": "Amazing experience!",
|
||||
"status": "PENDING",
|
||||
"created_at": "2024-02-18T14:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### List Reviews
|
||||
```http
|
||||
GET /api/v1/rides/{ride_id}/reviews/
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response:
|
||||
{
|
||||
"count": 150,
|
||||
"next": "http://api.thrillwiki.com/rides/1/reviews/?page=2",
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"author": {
|
||||
"id": 1,
|
||||
"username": "reviewer"
|
||||
},
|
||||
"rating": 5,
|
||||
"content": "Amazing experience!",
|
||||
"created_at": "2024-02-18T14:30:00Z",
|
||||
"media": [
|
||||
{
|
||||
"type": "image",
|
||||
"url": "https://media.thrillwiki.com/reviews/1/image.jpg"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Integrations
|
||||
|
||||
### Email Service Integration
|
||||
```http
|
||||
POST /api/v1/email/send/
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"template": "review_notification",
|
||||
"recipient": "user@example.com",
|
||||
"context": {
|
||||
"review_id": 1,
|
||||
"content": "Amazing experience!"
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"status": "sent",
|
||||
"message_id": "123abc",
|
||||
"sent_at": "2024-02-18T14:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Media Processing
|
||||
```http
|
||||
POST /api/v1/media/process/
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: [binary data]
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": 1,
|
||||
"original_url": "https://media.thrillwiki.com/original/image.jpg",
|
||||
"processed_url": "https://media.thrillwiki.com/processed/image.jpg",
|
||||
"thumbnail_url": "https://media.thrillwiki.com/thumbnails/image.jpg",
|
||||
"metadata": {
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"format": "jpeg",
|
||||
"size": 1024576
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Versioning
|
||||
|
||||
### Version Header
|
||||
```http
|
||||
Accept: application/json; version=1.0
|
||||
```
|
||||
|
||||
### Version Routes
|
||||
```python
|
||||
# urls.py
|
||||
urlpatterns = [
|
||||
path('v1/', include('api.v1.urls')),
|
||||
path('v2/', include('api.v2.urls')),
|
||||
]
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Response Format
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "validation_error",
|
||||
"message": "Invalid input data",
|
||||
"details": [
|
||||
{
|
||||
"field": "rating",
|
||||
"message": "Rating must be between 1 and 5"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Codes
|
||||
- `authentication_error`: Invalid or missing authentication
|
||||
- `permission_denied`: Insufficient permissions
|
||||
- `validation_error`: Invalid input data
|
||||
- `not_found`: Resource not found
|
||||
- `rate_limit_exceeded`: Too many requests
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Rate Limit Configuration
|
||||
```python
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_THROTTLE_CLASSES': [
|
||||
'rest_framework.throttling.AnonRateThrottle',
|
||||
'rest_framework.throttling.UserRateThrottle'
|
||||
],
|
||||
'DEFAULT_THROTTLE_RATES': {
|
||||
'anon': '100/day',
|
||||
'user': '1000/day',
|
||||
'burst': '20/minute'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limit Headers
|
||||
```http
|
||||
X-RateLimit-Limit: 1000
|
||||
X-RateLimit-Remaining: 999
|
||||
X-RateLimit-Reset: 1613664000
|
||||
```
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Swagger/OpenAPI
|
||||
```yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: ThrillWiki API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/parks:
|
||||
get:
|
||||
summary: List parks
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ParkList'
|
||||
```
|
||||
|
||||
### API Documentation URLs
|
||||
```python
|
||||
urlpatterns = [
|
||||
path('docs/', include_docs_urls(title='ThrillWiki API')),
|
||||
path('schema/', schema_view),
|
||||
]
|
||||
Reference in New Issue
Block a user