Secondhand Marketplace — Backend

A secondhand goods marketplace backend built with Spring Boot 3.5.4 and Java, featuring JWT-based stateless authentication and a SQLite database. Users can list, browse, search, favorite, message about, and rate advertisements, with an admin role for moderation.

Tech Stack

• Spring Boot (Web, Security, Validation)
• Spring Security + JWT (jjwt) for stateless authentication
• SQLite (sqlite-jdbc + Hibernate Community SQLite Dialect)
• Maven

Getting Started

mvn spring-boot:run

The application uses a SQLite database file (secondhand.db), which is initialized at startup via DatabaseInitializer.

Authentication

• Authentication is handled via JWT. The token must be sent in the Authorization header on protected requests.
• The following endpoints are publicly accessible without a token:
  • POST /api/users/register
  • POST /api/users/login
  • GET /api/categories
  • GET /api/cities
• All other endpoints require a valid JWT (anyRequest().authenticated() in SecurityConfig).
• Admin-only actions are enforced inside each controller by checking the authenticated user's role (role == ADMIN), on top of the base authentication requirement.

---

📌 API Reference

1. User — /api/users (UserController)

Method	Endpoint	Description	Access
POST	/api/users/register	Registers a new user (username, password, phone, email, fullName) and returns a JWT	Public
POST	/api/users/login	Logs in with username/password and returns a JWT	Public
GET	/api/users/me	Returns the profile of the currently authenticated user	Authenticated
GET	/api/users	Returns a list of all users	Admin only
PUT	/api/users/{id}/block	Blocks a user account	Admin only
PUT	/api/users/{id}/unblock	Unblocks a user account	Admin only

---

2. Advertisement — /api/ads (AdvertisementController)

Method	Endpoint	Description	Access
GET	/api/ads	Returns all active advertisements	Authenticated*
GET	/api/ads/{adId}	Returns a single advertisement by ID	Authenticated*
GET	/api/ads/user/{userId}	Returns all advertisements posted by a specific user	Authenticated*
POST	/api/ads	Creates a new advertisement (title, description, price, negotiable, categoryId, cityId, imagePaths)	Authenticated
PUT	/api/ads/{id}	Updates an advertisement	Authenticated (owner)
DELETE	/api/ads/{id}	Deletes an advertisement owned by the requester	Authenticated (owner)
POST	/api/ads/{id}/sold	Marks an advertisement as sold	Owner of the ad only
POST	/api/ads/{id}/approve	Approves a pending advertisement	Admin only
POST	/api/ads/{id}/reject	Rejects an advertisement (optional reason in the request body)	Admin only
GET	/api/ads/pending	Returns advertisements awaiting approval	Admin only
GET	/api/ads/search	Searches advertisements with filters (keyword, categoryId, cityId, minPrice, maxPrice)	Authenticated**
GET	/api/ads/admin/all	Returns all advertisements, including inactive/pending ones	Admin only
DELETE	/api/ads/{id}/admin	Deletes any advertisement (admin override)	Admin only
GET	/api/ads/admin/search	Searches advertisements for the admin panel (same filters as above)	Admin only

* These endpoints are not explicitly permitAll in SecurityConfig, so they require a valid token under the anyRequest().authenticated() rule, even though the controller logic itself doesn't check for a specific role. ** The principal is injected but currently unused for filtering results.

---

3. Category — /api/categories (CategoryController)

Method	Endpoint	Description	Access
GET	/api/categories	Returns all categories	Public
POST	/api/categories	Creates a new category	Admin only
PUT	/api/categories/{id}	Updates a category	Admin only
DELETE	/api/categories/{id}	Deletes a category (and cascades deletion of all advertisements in it)	Admin only

---

4. City — /api/cities (CityController)

Method	Endpoint	Description	Access
GET	/api/cities	Returns all cities	Public
POST	/api/cities	Creates a new city	Admin only
PUT	/api/cities/{id}	Updates a city	Admin only
DELETE	/api/cities/{id}	Deletes a city	Admin only

---

5. Conversation & Message — /api/conversations (ConversationController)

Method	Endpoint	Description	Access
POST	/api/conversations/messages	Starts a conversation on an advertisement (if none exists) and sends the first message	Authenticated
GET	/api/conversations	Returns the current user's conversations	Authenticated
GET	/api/conversations/{id}	Returns a single conversation by ID	Authenticated
GET	/api/conversations/{id}/messages	Returns all messages in a conversation	Authenticated
DELETE	/api/conversations/{id}	Closes/deletes a conversation	Authenticated
POST	/api/conversations/start	Explicitly starts a new conversation on an advertisement	Authenticated
POST	/api/conversations/{id}/messages	Adds a new message to an existing conversation	Authenticated

---

6. Favorite — /api/favorites (FavoriteController)

Method	Endpoint	Description	Access
POST	/api/favorites/{adId}	Adds an advertisement to the user's favorites	Authenticated
DELETE	/api/favorites/{adId}	Removes an advertisement from the user's favorites	Authenticated
GET	/api/favorites/user/{userId}	Returns a user's favorited advertisements	Authenticated
GET	/api/favorites/check/{adId}	Checks whether an advertisement is in the current user's favorites	Authenticated

---

7. Rating — /api/ratings (RatingController)

Method	Endpoint	Description	Access
POST	/api/ratings	Submits a rating for a seller based on an advertisement (adId, score, comment in the body)	Authenticated
GET	/api/ratings/seller/{sellerId}	Returns all ratings received by a seller	Public
GET	/api/ratings/seller/{sellerId}/average	Returns a seller's average rating	Public
GET	/api/ratings/has-rated/{adId}	Checks whether the current user has already rated a given advertisement	Authenticated
GET	/api/ratings/ad/{adId}	Returns all ratings submitted for a specific advertisement	Public

---

Project Structure (Summary)

src/main/java/org/example/
├── Controller/       # REST controllers (see API reference above)
├── service/           # Domain logic (interfaces + impl)
├── repository/        # Data access layer (interfaces + impl, JDBC over SQLite)
├── model/              # Entities (User, Advertisement, Category, City, Conversation, Message, Rating, Favorite, ...)
├── dto/                # Request/Response DTOs
├── security/           # JWT util, authentication filter, AuthenticatedUser
├── config/             # SecurityConfig
├── enums/              # UserRole, UserStatus, AdvertisementStatus, SortType
├── exception/          # ResourceNotFoundException, UnauthorizedException
└── database/           # DatabaseManager, DatabaseInitializer

This README was written by directly inspecting the controller and security-config source code, and covers every endpoint currently exposed by the API.