API Documentation - bounswe/bounswe2024group3 GitHub Wiki
Login
Let's an existing user login by sending its username and password. Attaches auth cookies to the response.
Request
POST api/login
{
"username": "",
"password": ""
}
Response
{
"message": "Login successful",
"username": "",
"user_id": "",
"name": "",
"surname": "",
"email": "",
"labels": ""
}
{
"error": "Invalid username or password",
}
Register
Let's a user register to Spot On.
Request
POST api/register
{
"name": "",
"surname": "",
"username": "",
"email": "",
"password": "",
"labels": ""
}
Response
{
"message": "Registration successful",
"username": "",
"user_id": "",
"name": "",
"surname": "",
"email": "",
"labels": ""
}
{
"error": "Username already exists"
}
{
"error": "Email already registered"
}
Forget password
Initializes the "forgot password" workflow. When this endpoint is called, if the user with the email provided exists, the user gets an email that has a link to the password reset page.
Request
POST api/forget-password
{
"email": ""
}
Response
{
"success": "We have sent you a link to reset your password"
}
{
"error": "User with credentials not found"
}
Reset password
The second part of the "forget password" workflow. The request must have a valid "reset token". The "reset token" is only given to the user via an email, that has the reset token embedded in the spotonapp.win url.
Request
POST api/reset-password
{
"token": "",
"new_password": "",
"confirm_password": ""
}
Response
{
"success": "Password updated"
}
{
"error": "Passwords do not match"
}
{
"error": "No user found"
}
Get user
Gets the current authenticated user.
Request
GET api/get_user
Response
{
"message": "User details retrieved",
"username": "",
"user_id": "",
"name": "",
"surname": "",
"email": "",
"labels": ""
}
{
"error": "User not authenticated"
}
Logout
Current authenticated user is logged out.
Request
POST api/logout
Response
{
"message": "Logout successful"
}
Follow
Follows a user. Must be authenticated.
Request
POST api/follow/<int: user_id>
Response
{
"message": "You are now following ..."
}
Unfollow
Unfollows a user. Must be authenticated
Request
POST api/unfollow/<int: user_id>
Response
{
"message": "You have unfollowed ..."
}
Create post
Create a post. Must be authenticated.
Request
POST api/create-post
{
"link": "",
"image": "",
"comment": "",
"latitude": "",
"longitude": "",
}
Response
{
"message": "Post created successfully",
"post_id": ""
}
{
"error": "Failed to fetch content description"
}
Get user posts
Gets a user's posts. Must be authenticated.
Request
GET api/get-user-posts?user_id=&page_number=&page_size=
Response
{
"posts": [
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"tags": [""]
}
],
"current_page": "",
"total_pages": "",
"total_posts": ""
}
Get posts
Get specific post(s) by providing either:
- post id: Get post with ID
- post link: Get all posts for spotify link
- start date & end date: Posts between date
The last option returns paginated data and requires fields page_number and page_size to be present.
Request
POST api/get-posts
{
"post_id": "",
}
or
POST api/get-posts
{
"post_link": "",
}
or
POST api/get-posts
{
"start_date": "",
"end_date": "",
"page_number": "",
"page_size": "",
}
Response
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"content": {
"id": "",
"link": "",
"description": "",
"content_type": ""
}
"tags": [""]
}
"posts": [
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"content": {
"id": "",
"link": "",
"description": "",
"content_type": ""
}
"tags": [""]
}
]
Like post
Likes a post. Must be authenticated.
Request
POST api/posts/<int:post_id>/like
Response
{
"status": "success",
"message": "Post liked"
}
{
"status": "success",
"message": "Post not found"
}
{
"status": "success",
"message": "Post already liked"
}
Dislike post
Dislike post. Must be authenticated.
Request
POST api/posts/<int:post_id>/dislike
Response
{
"status": "success",
"message": "Post disliked"
}
{
"status": "success",
"message": "Post not found"
}
{
"status": "success",
"message": "Post already disliked"
}
Most shared nearby
Most shared posts nearby the user. Must be authenticated.
Request
GET api/most-shared-nearby-things?latitude=&longitude=&radius=&page=&size=
Response
{
"songs": [
{
"id": "",
"comment": "",
"image": "",
"link": "",
"created_at": "",
"total_likes": "",
"total_dislikes": "",
"content": {
"id": "",
"link": "",
"description": "",
"content_type": ""
}
"tags": [""]
}
],
"pagination": {
"page": "",
"size": "",
"total_pages": "",
"total_songs": ""
}
}
{
"error": "Invalid input for latitude, longitude, radius, page, or size."
}
Save now playing
Saves what user plays. Must be authenticated.
Request
POST api/save-now-playing
{
"link": "",
"latitude": "",
"longitude": ""
}
Response
{
"message": "Now playing data saved successfully.",
"id": ""
}
Most listened nearby
Returns most listened songs nearby a user. Must be authenticated.
Request
GET api/most-listened-nearby?latitude=&longitude=&radius=
Response
{
"tracks": [
{
"link": "",
"description": "",
"count": ""
}
]
}
Search
Search in posts on Spot On
Request
GET api/search?search=&page=&page_size=
Response
{
"content_results_count": "",
"profile_results_count": "",
"page": "",
"page_size": "",
"contents": [
{
"id": "",
"link": "",
"description": "",
"content_type": "",
"artist_names": [""],
"playlist_name": "",
"album_name": "",
"song_name": "",
"genres": [""],
"ai_description": "",
"lyrics": ""
}
],
"profiles": [
{
"id": "",
"user_id": "",
"name": "",
"surname": "",
"labels": [""],
"username": "",
}
],
}
Random Song
Fetches random songs from Spotify
Request
GET api/random-songs?limit=&genre=&q=
Response
{
"songs": [
{
"link": "",
"name": "",
"artist": ""
}
],
"count": "",
}
Get Pages Of Spotify Embeds
Fetch posts with AI descriptions and content suggestions
Request
GET api/get_pages_of_spot_embeds?id=&link=&start_date=&end_date=&page=&page_size=
Response
{
'id': "",
'link': "",
'content_type': "",
'artist_names': "",
'playlist_name': "",
'album_name': "",
'song_name': "",
'genres': "",
'ai_description': "",
'suggestions': [{
'name': "",
'artist': "",
'spotify_url': "",
'reason': ""
}]
}
Get Lyrics
Get lyrics from database or fetch from Musixmatch if not available. Query parameters: - spotify_url: Spotify URL to lookup content and fetch lyrics - force_refresh: Optional boolean to force refresh lyrics from Musixmatch
Request
GET api/get_lyrics?spotify_url=&force_refresh=
Response
{
"lyrics": "",
"source": "",
"source_url": ""
}
Get Song Quiz Lyrics
Request
GET api/get_song_quiz_lyrics
Response
{
"lyric_snippet": "",
"options": [
{
"link": "",
"name": "",
"artist": ""
},
{
"link": "",
"name": "",
"artist": ""
},
{
"link": "",
"name": "",
"artist": ""
}
],
"correct_link": ""
}
Search Spotify
This endpoint allows searching for tracks, albums, or artists on Spotify using a query string.
You can optionally specify the type of content to search (track, album, artist) and the number of results.
Request
GET api/search_spotify?q={query}&type={track,album,artist}&limit={1-50}
{
"results": {
"tracks": [
{
"id": "",
"name": "",
"artists": [""],
"album": "",
"preview_url": "",
"external_url": "",
"image_url": ""
}
],
"albums": [
{
"id": "",
"name": "",
"artists": [""],
"release_date": "",
"external_url": "",
"image_url": ""
}
],
"artists": [
{
"id": "",
"name": "",
"genres": [""],
"external_url": "",
"image_url": ""
}
]
},
"query": ""
}
Authenticate on Spotify
This endpoint generates a Spotify authorization URL that the user can visit to connect their Spotify account. It does not require authentication.
Request
GET api/spotify/auth/
{
"auth_url": "string"
}
User Spotify Status
This endpoint checks if the user is currently connected to Spotify.
If connected, it returns connected: true; otherwise, connected: false.
Request
GET api/spotify/status/
Response
{
"connected": true
}
Redirect Spotify Callback
This endpoint is called by Spotify after the user grants permission. It exchanges the code parameter for an access token, refresh token, and user profile information. On success, it associates the tokens with the currently authenticated user and redirects the user to a predefined frontend URL.
Request
GET api/spotify/callback/?code={authorization_code}
Response
On success (redirects to frontend): No direct JSON response. The user is redirected to https://spotonapp.win/view-playlist?connected=true
On error:
{
"error": "string"
}