API Endpoints Documentation

API Documentation

Table of Contents

• Authentication
• Challenges
• Comments
• Home Page
• Posts
• Post Likes
• Profile
• Search
• Users
• Waste Goals
• Waste Logs

---

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