Cupcake
f6858e6ea1
- Data fetched from Open5e API: 3,215 items (339 spells, 330 creatures, 24 classes, 2,319 magic items, 203 equipment) - FastAPI app with API key auth (X-API-Key header or ?api_key= param) - Sliding window rate limiting (60 req/min, 10K req/day) - Dice rolling endpoint (e.g., /api/dice/roll?spec=2d20+5) - Full-text search across all resource types - Pagination, filtering (name, level, school, class, etc.) - Admin CLI for API key management - nginx + systemd service ready for deployment
59 lines
No EOL
1.8 KiB
Markdown
59 lines
No EOL
1.8 KiB
Markdown
# D&D SRD 5.2 API
|
|
|
|
An open REST API for the Dungeons & Dragons 5.2 System Reference Document (SRD), served at **[dnd.jezzahehn.com](https://dnd.jezzahehn.com)**.
|
|
|
|
Powered by [Open5e](https://api.open5e.com) data with flat JSON caching.
|
|
|
|
## Endpoints
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `GET /api` | API root — list all available resources |
|
|
| `GET /api/spells` | List spells (filter by name, level, school, class, etc.) |
|
|
| `GET /api/spells/{key}` | Get a specific spell |
|
|
| `GET /api/creatures` | List creatures/monsters |
|
|
| `GET /api/creatures/{key}` | Get a specific creature |
|
|
| `GET /api/classes` | List classes |
|
|
| `GET /api/classes/{key}` | Get a specific class |
|
|
| `GET /api/magic-items` | List magic items |
|
|
| `GET /api/magic-items/{key}` | Get a specific magic item |
|
|
| `GET /api/equipment` | List equipment |
|
|
| `GET /api/equipment/{key}` | Get specific equipment |
|
|
| `GET /api/dice/roll` | Roll dice (`?spec=2d20+5`) |
|
|
| `GET /api/search` | Search across all resources (`?q=fireball`) |
|
|
| `GET /api/docs` | Interactive API documentation (Swagger UI) |
|
|
|
|
## Authentication
|
|
|
|
Pass your API key via `X-API-Key` header or `?api_key=` query parameter.
|
|
|
|
```bash
|
|
curl -H "X-API-Key: your-key-here" https://dnd.jezzahehn.com/api/spells
|
|
```
|
|
|
|
## Running Locally
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
python scripts/fetch_data.py
|
|
uvicorn app.main:app --reload
|
|
```
|
|
|
|
## Managing API Keys
|
|
|
|
```bash
|
|
python scripts/manage_keys.py list # List all keys
|
|
python scripts/manage_keys.py create "name" # Create a new key
|
|
python scripts/manage_keys.py revoke <key> # Revoke a key
|
|
```
|
|
|
|
## Data
|
|
|
|
- **Spells:** 339
|
|
- **Creatures:** 330
|
|
- **Classes:** 24
|
|
- **Magic Items:** 2,319
|
|
- **Equipment:** 203
|
|
- **Total:** 3,215 items
|
|
|
|
Data is fetched from [Open5e](https://api.open5e.com) and cached as flat JSON files in `data/`. |