96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
# API Server
|
|
|
|
A modern FastAPI-based backend providing various endpoints for media, authentication, lighting control, and more.
|
|
|
|
## Overview
|
|
|
|
This server is built with [FastAPI](https://fastapi.tiangolo.com/) and provides a comprehensive API for multiple services. API documentation is available in three formats:
|
|
- **Swagger UI**: [https://api.codey.lol/docs](https://api.codey.lol/docs) - Classic interactive API explorer with "Try it out" functionality
|
|
- **Scalar**: [https://api.codey.lol/scalar](https://api.codey.lol/scalar) - Modern, fast interactive API documentation (recommended)
|
|
- **ReDoc**: [https://api.codey.lol/redoc](https://api.codey.lol/redoc) - Clean, read-only documentation with better visual design
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication (`/auth/`) 🔐
|
|
- `POST /auth/login` - User authentication with username/password (OAuth2 form data)
|
|
- `POST /auth/refresh` - Refresh access tokens using refresh token from cookies
|
|
- `GET /auth/id` - Get current user information (requires authentication)
|
|
|
|
### Lighting Control (`/lighting/`) 💡
|
|
- `GET /lighting/state` - Get current lighting state from Redis cache
|
|
- `POST /lighting/state` - Set lighting state and control GE Cync smart lights
|
|
- Supports power on/off, brightness (0-100), and RGB color control
|
|
- Directly interfaces with Cync cloud API for real-time device control
|
|
- Requires authentication
|
|
|
|
### Radio & Streaming (`/radio/`) 📻
|
|
**Public Endpoints:**
|
|
- `POST /radio/np` - Get currently playing track information (by station: main, rock, rap, electronic, pop)
|
|
- `POST /radio/typeahead` - Search typeahead for song/artist suggestions
|
|
- `POST /radio/get_queue` - Get current play queue (paged, 20 results per page)
|
|
- `GET /radio/album_art` - Get album art for current or specified track
|
|
|
|
**Authenticated Endpoints:**
|
|
- `POST /radio/request` - Submit song requests to radio stations
|
|
- `POST /radio/skip` - Skip to next track or specific UUID in queue
|
|
- `POST /radio/queue_shift` - Reorder items in the play queue
|
|
- `POST /radio/reshuffle` - Reshuffle the entire play queue
|
|
- `POST /radio/queue_remove` - Remove specific items from queue
|
|
- `POST /radio/ls._next_` - Get next track (for Liquidsoap integration)
|
|
|
|
**WebSocket Real-time Updates:**
|
|
- `WS /radio/ws/{station}` - Real-time radio updates via WebSocket
|
|
- Connects to specific radio station (main, rock, rap, electronic, pop)
|
|
- Immediately sends current track information on connect
|
|
- Sends real-time updates when tracks change
|
|
- Provides LRC (synchronized lyrics) data when available
|
|
- Message types: `track_change`, `lrc`, `ack`
|
|
- No authentication required
|
|
|
|
### Content & Media
|
|
**YouTube (`/yt/`)** 🎥
|
|
- `POST /yt/search` - Search for YouTube videos by title
|
|
|
|
**Transcriptions (`/transcriptions/`)** 📝
|
|
- `POST /transcriptions/get_episodes` - Get episode list by show ID
|
|
- `POST /transcriptions/get_episode_lines` - Get transcript lines for specific episodes
|
|
|
|
**Lyric Search (`/lyric/`)** 🎵
|
|
- `POST /lyric/search` - Search for song lyrics across multiple sources
|
|
- Supports artist/song search, text search within lyrics
|
|
- Optional LRC format and extra metadata
|
|
- Configurable source exclusions
|
|
|
|
**Random Messages (`/randmsg`)** 🎲
|
|
- `POST /randmsg` - Generate random messages (optional short format)
|
|
|
|
### System Widgets (`/widget/`) 📊
|
|
Homepage dashboard widgets for system monitoring:
|
|
- `GET /widget/redis` - Redis server statistics
|
|
- `GET /widget/sqlite` - SQLite database statistics
|
|
- `GET /widget/lyrics` - Lyrics database statistics
|
|
- `GET /widget/radio` - Current radio playing information
|
|
- `GET /widget/rq` - Background job queue statistics
|
|
|
|
### Utilities (`/misc/`) 🛠️
|
|
- `GET /misc/get_activity_image` - Retrieve current activity status image
|
|
- `GET /misc/no` - Get a random "no" reason/response
|
|
- `POST /misc/upload_activity_image` - Upload new activity image (API key required)
|
|
|
|
## Features
|
|
|
|
- **Rate Limiting**: All endpoints protected with configurable rate limits
|
|
- **Authentication**: JWT-based authentication with refresh tokens
|
|
- **Real-time Device Control**: Direct integration with smart home devices (Cync lights)
|
|
- **Redis Caching**: Fast data retrieval with Redis backend
|
|
- **Comprehensive Logging**: Detailed logging for debugging and monitoring
|
|
- **Interactive Documentation**: Auto-generated Swagger/OpenAPI docs
|
|
|
|
## Technology Stack
|
|
|
|
- **FastAPI** - Modern, fast web framework for building APIs
|
|
- **Redis** - In-memory data store for caching and session management
|
|
- **JWT** - Secure authentication tokens
|
|
- **aiohttp** - Async HTTP client for external API calls
|
|
- **Pydantic** - Data validation and serialization
|
|
- ... |