API Endpoints Documentation - bounswe/bounswe2025group5 GitHub Wiki

API Documentation

Table of Contents

Authentication

AuthController - Handles user authentication and registration

Endpoints:

  • POST /api/auth/login

    • Authenticates a user
    • Request Body: LoginRequest (username, password)
    • Returns: LoginResponse with authentication details

  • POST /api/auth/register

    • Registers a new user
    • Request Body: RegisterRequest (username, email, password)
    • Returns: RegisterResponse with registration status

Challenges

ChallengeController - Manages challenges and leaderboards

Endpoints:

  • POST /api/challenges/create

    • Creates a new challenge
    • Request Body: CreateChallengeRequest
    • Returns: ChallengeResponse with created challenge details

  • PUT /api/challenges/end/{id}

    • Ends a specific challenge
    • Path Variable: id (challenge ID)
    • Returns: EndChallengeResponse with ending status

  • POST /api/challenges/attend

    • Allows a user to attend a challenge
    • Request Body: AttendChallengeRequest
    • Returns: AttendChallengeResponse with attendance status

  • DELETE /api/challenges/leave/{username}/{challengeId}

    • Allows a user to leave a challenge
    • Path Variables: username, challengeId
    • Returns: LeaveChallengeResponse with leave status

  • GET /api/challenges/leaderboard

    • Gets leaderboard for a specific challenge
    • Query Param: id (challenge ID)
    • Returns: List of LeaderboardEntry objects

  • GET /api/challenges

    • Gets all challenges for a user
    • Query Param: username
    • Returns: List of ChallengeListResponse objects

Comments

CommentController - Manages post comments

Endpoints:

  • POST /api/comments

    • Adds a new comment to a post
    • Request Body: CommentRequest (content, username, postId)
    • Returns: CommentResponse with comment details

  • PUT /api/comments/{commentId}

    • Updates an existing comment
    • Path Variable: commentId
    • Request Body: CommentRequest
    • Returns: Updated CommentResponse

  • DELETE /api/comments/{commentId}

    • Deletes a comment
    • Path Variable: commentId
    • Returns: Map with deletion status

  • GET /api/comments/post/{postId}

    • Gets all comments for a post
    • Path Variable: postId
    • Returns: GetCommentsResponse with list of comments

Home Page

HomePageController - Provides home page content

Endpoints:

  • GET /api/home/getMotivated

    • Fetches a random motivational quote
    • Returns: MotivationalQuoteResponse

  • GET /api/home/number/{number}

    • Gets trivia about a specific number
    • Path Variable: number
    • Returns: NumberTriviaResponse

  • GET /api/home/getAirQuality

    • Gets air quality data for a location
    • Query Param: location
    • Returns: AirQualityResponse

Posts

PostController - Manages user posts

Endpoints:

  • GET /api/posts/info

    • Gets paginated posts
    • Query Params: username (optional), size, lastPostId (optional)
    • Returns: List of GetPostResponse objects

  • POST /api/posts/create

    • Creates a new post (supports text and image)
    • Form Data: content, username, photoFile (optional)
    • Returns: CreateOrEditPostResponse

  • PUT /api/posts/edit/{postId}

    • Edits an existing post
    • Path Variable: postId
    • Form Data: content, username, photoFile (optional)
    • Returns: CreateOrEditPostResponse

  • DELETE /api/posts/delete/{postId}

    • Deletes a post
    • Path Variable: postId
    • Returns: DeletePostResponse

  • GET /api/posts/mostLikedPosts

    • Gets most liked posts
    • Query Params: username (optional), size
    • Returns: List of GetPostResponse objects

  • POST /api/posts/save

    • Saves a post for a user
    • Request Body: SavePostRequest
    • Returns: SavePostResponse

  • DELETE /api/posts/unsave{username}/{postId}

    • Unsaves a post
    • Path Variables: username, postId
    • Returns: Map with deletion status

  • GET /api/posts/getSavedPosts

    • Gets all saved posts for a user
    • Query Param: username
    • Returns: List of GetSavedPostResponse objects

  • GET /api/posts/getPostsForUser

    • Gets all posts by a specific user
    • Query Param: username
    • Returns: List of GetPostResponse objects

Post Likes

PostLikeController - Manages post likes

Endpoints:

  • POST /api/posts/like

    • Adds a like to a post
    • Request Body: PostLikeRequest (username, postId)
    • Returns: Map with like status

  • DELETE /api/posts/like

    • Removes a like from a post
    • Request Body: PostLikeRequest
    • Returns: Map with unlike status

  • GET /api/posts/{postId}/likes

    • Gets all likes for a post
    • Path Variable: postId
    • Returns: PostLikeResponse with like count and details

Profile

ProfileController - Manages user profiles

Endpoints:

  • GET /api/profile/info

    • Gets profile information
    • Query Param: username
    • Returns: ProfileResponse

  • PUT /api/profile/edit

    • Edits profile information
    • Request Body: ProfileEditAndCreateRequest
    • Returns: Updated ProfileResponse

  • POST /api/profile/{username}/photo

    • Uploads a profile photo
    • Path Variable: username
    • Form Data: file (image)
    • Returns: ProfileResponse with updated photo URL

  • GET /api/profile/badges

    • Gets user badges
    • Query Param: username
    • Returns: List of BadgeResponse objects

Search

SearchController - Provides search functionality

Endpoints:

  • GET /api/search/posts/semantic
    • Searches posts semantically
    • Query Params: query (search term), username (optional), lang (language, default "en")
    • Returns: List of GetPostResponse objects matching the query

Users

UserController - Provides user statistics

Endpoints:

  • GET /api/users/count
    • Gets total user count
    • Returns: UserCountResponse

Waste Goals

WasteGoalController - Manages waste reduction goals

Endpoints:

  • GET /api/goals/info

    • Gets paginated waste goals
    • Query Params: username, size, lastGoalId (optional)
    • Returns: List of GetWasteGoalResponse objects

  • POST /api/goals/create

    • Creates a new waste goal
    • Request Body: CreateWasteGoalRequest
    • Returns: CreateWasteGoalResponse

  • PUT /api/goals/edit/{goalId}

    • Edits an existing waste goal
    • Path Variable: goalId
    • Request Body: Updated WasteGoal object
    • Returns: CreateWasteGoalResponse

  • DELETE /api/goals/delete/{goalId}

    • Deletes a waste goal
    • Path Variable: goalId
    • Returns: DeleteWasteGoalResponse

Waste Logs

WasteLogController - Manages waste tracking logs

Endpoints:

  • GET /api/logs/get

    • Gets waste logs for a goal
    • Query Param: goalId
    • Returns: List of GetWasteLogResponse objects

  • POST /api/logs/create

    • Creates a new waste log
    • Request Body: CreateWasteLogRequest
    • Returns: CreateOrEditWasteLogResponse

  • PUT /api/logs/update/{logId}

    • Updates a waste log
    • Path Variable: logId
    • Request Body: UpdateWasteLogRequest
    • Returns: CreateOrEditWasteLogResponse

  • DELETE /api/logs/delete/{logId}

    • Deletes a waste log
    • Path Variable: logId
    • Returns: DeleteWasteLogResponse

  • GET /api/logs/totalLogAmountForIntervalAndType

    • Gets total waste amount for a specific type and time interval
    • Query Params: startDate, endDate, wasteType
    • Returns: TotalLogResponse