Archived
96 lines
8.5 KiB
Markdown
96 lines
8.5 KiB
Markdown
# Eurovision 25 Backend
|
||
|
||
This is the backend system for the Eurovision 25 application. It provides the necessary APIs and services to support the frontend, including:
|
||
|
||
- **Voting Management**: Handle voting submissions and results.
|
||
- **Participant Data**: Manage information about participating countries and artists.
|
||
- **Event Scheduling**: Provide details about the event schedule and performances.
|
||
|
||
## Endpoints
|
||
### **Admin Endpoints**
|
||
|
||
**User Management**
|
||
|
||
- `POST /admin/users`: Add a user (assign to a group).
|
||
- `GET /admin/users`: List all users (with `is_active` filter).
|
||
- `PUT /admin/users/{user_id}`: Edit user (e.g., toggle `is_active`, change group).
|
||
|
||
**Group Management**
|
||
|
||
- `POST /admin/groups`: Create a group (e.g., "Berlin Household").
|
||
- `PUT /admin/groups/{group_id}`: Edit group (e.g., rename, toggle `is_active`).
|
||
|
||
**Contest & Song Management**
|
||
|
||
- `POST /admin/contests`: Create a contest.
|
||
- `PUT /admin/contests/{contest_id}`: Edit contest (title, status).
|
||
- `POST /admin/contests/{contest_id}/songs`: Add a song to the contest.
|
||
- `PUT /admin/contests/{contest_id}/songs/{song_id}`: Edit song details (lyrics, tags).
|
||
- `PUT /admin/contests/{contest_id}/activate`: Start the contest.
|
||
- `PUT /admin/contests/{contest_id}/close`: End the contest (freeze reviews).
|
||
|
||
---
|
||
|
||
### **User Authentication**
|
||
|
||
- `POST /login`: Authenticate with username/password (returns JWT token).
|
||
|
||
---
|
||
|
||
### **Game Flow Endpoints**
|
||
|
||
**Contest Data**
|
||
|
||
- `GET /contests/active`: Get active contest metadata (status, closure time).
|
||
- `GET /contests/active/songs`: List all songs (with country, artist, lyrics, tags, AI interpretation).
|
||
|
||
**Review Management**
|
||
|
||
- `POST /reviews`: Submit review for a song (song/wardrobe/stage scores + optional text).
|
||
- `PUT /reviews/{review_id}`: Edit review (blocked if contest is closed).
|
||
- `GET /reviews/me`: Get all reviews submitted by the current user for the active contest.
|
||
|
||
---
|
||
|
||
### **Results & Statistics**
|
||
|
||
**Core Results**
|
||
|
||
- `GET /scores/groups`: Scores aggregated by group.
|
||
- `GET /scores/unified`: Global combined scores.
|
||
|
||
**Detailed Statistics**
|
||
|
||
- `GET /stats/categories`: Top songs in each category (song, wardrobe, stage) – switchable between group/global via query param `?scope=group|global`.
|
||
- `GET /stats/rankings`: Full ranked song list (sorted by total score) – scope filterable.
|
||
- `GET /stats/consistency`: Standard deviation of scores per song (identify divisive entries).
|
||
- `GET /stats/group-comparison`: Compare average scores between groups (e.g., "London vs. Madrid").
|
||
|
||
---
|
||
|
||
| **Name** | **Operation** | **URL** | **Description** |
|
||
| ------------------------ | ------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| **Admin Endpoints** | | | |
|
||
| Add User | POST | `/admin/users` | Add a new user (assign to a group). |
|
||
| List Users | GET | `/admin/users` | List all users (filter by `is_active`). |
|
||
| Edit User | PUT | `/admin/users/{user_id}` | Edit user details (e.g., toggle `is_active`, change group). |
|
||
| Create Group | POST | `/admin/groups` | Create a new group (e.g., "Berlin Household"). |
|
||
| Edit Group | PUT | `/admin/groups/{group_id}` | Edit group details (e.g., rename, toggle `is_active`). |
|
||
| Create Contest | POST | `/admin/contests` | Create a new contest. |
|
||
| Edit Contest | PUT | `/admin/contests/{contest_id}` | Edit contest details (e.g., title, status). |
|
||
| Add Song | POST | `/admin/contests/{contest_id}/songs` | Add a song to the contest (includes lyrics, tags, etc.). |
|
||
| Edit Song | PUT | `/admin/contests/{contest_id}/songs/{song_id}` | Edit song details (e.g., lyrics, tags). |
|
||
| Activate Contest | PUT | `/admin/contests/{contest_id}/activate` | Start the contest (allow reviews). |
|
||
| Close Contest | PUT | `/admin/contests/{contest_id}/close` | End the contest (freeze reviews). |
|
||
| **User Authentication** | | | |
|
||
| Login | POST | `/login` | Authenticate user (returns JWT token). |
|
||
| **Game Flow Endpoints** | | | |
|
||
| Get Active Contest | GET | `/contests/active` | Fetch metadata of the active contest (e.g., status, closure time). |
|
||
| List Songs | GET | `/contests/active/songs` | List all songs in the active contest (with lyrics, tags, AI interpretation). |
|
||
| Submit Review | POST | `/reviews` | Submit review for a song (song/wardrobe/stage scores + optional text). |
|
||
| Edit Review | PUT | `/reviews/{review_id}` | Edit review (blocked if contest is closed). |
|
||
| Get User Reviews | GET | `/reviews/me` | Fetch all reviews submitted by the current user for the active contest. |
|
||
| **Results & Statistics** | | | |
|
||
| Extra | GET | `/stats/extra` | A dictionary of the following:<br> - Song with the highest standard deviation in total scores.<br> - Most common tag among top 25% of songs + example song.<br> |
|
||
|
||
--- |