VideoGames Catalogue Backend

VideoGames Catalogue Backend is a Spring Boot application that provides a REST API for fetching, managing, and commenting on video games. It integrates with an external game API to populate the database automatically and supports role-based access for administrators and users. This backend is designed to support a frontend application or mobile app for video game enthusiasts.

Table of Contents

• Key Features
• Running the backend locally
• Swagger documentation
• API Endpoint Details
• Automatic Game Fetch on Application Startup
• Scheduled Daily Game Fetch
• Postman

Key Features

• JWT-based authentication and authorization
• User profile management
• Commenting for games
• Integration with an external games API
• Admin endpoints for managing game data
• Automatic and scheduled game fetching

Running the backend locally

1. Before running the backend, make sure the following tools are installed:

Java 17 or higher

Check if installed:

java -version

Expected:

openjdk version "17.x.x"

If Java is missing or the version is lower than 17, download it: https://www.oracle.com/java/technologies/downloads/

Maven

Maven is used to build and run the application.

Check if installed:

mvn -version

Expected:

Apache Maven 3.x.x

If Maven is missing, install it: https://maven.apache.org/download.cgi

Git

Used to clone the project.

Check if installed:

git --version

Expected:

git version 2.x.x

If Git is not installed: https://git-scm.com/

2. Clone the repository:

   git clone https://github.com/mategames-team/backend.git
   cd backend
   git checkout dev

3. Build and run the project using Maven:

   mvn spring-boot:run

Swagger documentation

To test endpoints use Swagger documentation by link (when running the app locally, instructions below): http://localhost:8080/api/swagger-ui/index.html

How to Use the API Documentation (Swagger UI)

Important! To run manual update of the database using AdminGameController endpoints, you need to log in as ADMIN. This API uses JWT authentication. To access protected endpoints, you must register, log in, and authorise Swagger with your token.

1️⃣ Register a New User

• Open Swagger UI
• Find the Authentication section
• Click POST /auth/register
• Click “Try it out”
• Fill in the request body
• Click Execute ✅ If registration is successful, the user is created.

2️⃣ Log In and Get JWT Token

• In the Authentication section
• Open POST /auth/login
• Click “Try it out”
• Enter your credentials
• Click Execute 📌 The response will contain a JWT token, for example: { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } 👉 Copy this token

3️⃣ Authorise Swagger with JWT Token

• At the top-right corner of Swagger UI, click the 🔒 Authorize button
• In the popup window:
• Paste your token in this format:
• Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ⚠️ Important: The word Bearer and a space must be included
• Click Authorize
• Click Close ✅ Swagger is now authorised

4️⃣ Call Protected Endpoints Once authorised, you can access endpoints that require authentication. 📌 Swagger will now automatically attach the JWT token to each authorised request.

5️⃣ Logging Out / Token Expiry If you refresh the page or your token expires:

• Click 🔒 Authorize again
• Paste a new token

API Endpoint Details.

GameController

getAllGamesFromDb

• Description: Returns a page of games from DB.
• URL: http://localhost:8080/api/games/local
• Method: GET
• Authentication: Not required

getByApiId

• Description: Returns a game from db by its apiId if the game is in db. Fetches the game from API if there is no game by the provided apiId.
• URL: http://localhost:8080/api/games/{gameApiId}
• Method: GET
• Authentication: Not required

getAllGamesFromApi

• Description: Returns a paginated list of games fetched from the external API.
• URL: http://localhost:8080/api/games
• Method: GET
• Authentication: Not required

search

• Description: Searches local database games using search parameters.
• URL: http://localhost:8080/api/games/local/search
• Method: GET
• Authentication: Not required

apiSearch

• Description: Searches games directly from the external API.
• URL: http://localhost:8080/api/games/search
• Method: GET
• Authentication: Not required

AuthenticationController

registerUser

• Description: Registers a new user.
• URL: http://localhost:8080/api/auth/registration
• Method: POST

login

_ Description: Authenticates a user and returns JWT token.

• URL: http://localhost:8080/api/auth/login
• Method: POST

CommentController

createComment

• Description: Creates a new comment for a specific game.
• URL: http://localhost:8080/api/comments/games/{gameApiId}
• Method: POST
• Authentication: Required

getCommentsForGame

• Description: Returns a paginated list of comments for a specific game.
• URL: http://localhost:8080/api/games/{gameApiId}/comments
• Method: GET
• Authentication: Not required

getUserComments

• Description: Returns a paginated list of comments created by the authenticated user or a user by id.
• URL: http://localhost:8080/api/comments
• Method: GET
• Authentication: Not required

updateComment

• Description: Updates an existing comment owned by the authenticated user.
• URL: http://localhost:8080/api/comments/{commentId}
• Method: PATCH
• Authentication: Required

deleteComment

• Description: Deletes a comment owned by the authenticated user.
• URL: http://localhost:8080/api/comments/{commentId}
• Method: DELETE
• Authentication: Required

UserController

getUserInfo

• Description: Returns user information. If id is provided, returns info by id. If id is not provided, returns info about authenticated user. Any user can see other user's profile info.
• URL: http://localhost:8080/api/users/info
• Method: GET
• @RequestParam(required = false) Long id
• Authentication: not required

updateUserInfo

• Description: Updates the authenticated user’s profile information (profileName, email, about, location).
• URL: http://localhost:8080/api/users/me
• Method: PATCH
• Authentication: Required

changePassword

• Description: Changes the authenticated user’s password.
• URL: http://localhost:8080/api/users/me/password
• Method: PATCH
• Authentication: Required

UserGameController

createOrUpdateUserGame

• Description: Creates or updates a game associated with the authenticated user.
• URL: http://localhost:8080/api/user-games
• Method: POST
• Authentication: Required

deleteUserGame

• Description: Removes a game from the authenticated user’s list.
• URL: http://localhost:8080/api/user-games/{apiId}
• Method: DELETE
• Authentication: Required

getUserGamesByStatus

• Description: Returns a paginated list of any user’s games filtered by status.
• URL: http://localhost:8080/api/user-games
• Method: GET
• Authentication: Not required

AdminGameController

Provides administrative endpoints for managing game data fetched from an external API. These endpoints are intended only for administrators and are protected by role-based security. Important! To run manual update of the database using AdminGameController endpoints, you need to log in as ADMIN.

fetchBestGamesManually

• Description: Fetches the current list of best games from the external API and saves only games that do not already exist in the database.
• URL: http://localhost:8080/api/admin/fetch-best-games
• Method: POST
• Authentication: Required

fetchAndUpdateAllGamesManually

• Description: Fetches the best games from the external API and updates existing records, while also saving any newly discovered games.
• URL: http://localhost:8080/api/admin/fetch-update-best-games
• Method: POST
• Authentication: Required

Automatic Game Fetch on Application Startup

The application is configured to automatically fetch best games from the external API when the backend starts.

How It Works

• The main Spring Boot application class implements CommandLineRunner
• On startup, Spring executes the run() method
• This triggers an automatic call to gameService
• As a result, the application ensures that the database is initially populated with best games without requiring any manual admin action.

Scheduled Daily Game Fetch

The application includes a scheduled task that automatically fetches best games once per day.

• At specified time
• At specified time zone
• The scheduler runs automatically without any manual intervention
• Only new games are saved

Postman

A Postman collection is available to simplify testing the API. 👉 Open Online Bookstore Postman Collection

How to use this Postman collection:

1. Click the link above.
2. Import the collection into your Postman app.
3. Run requests against http://localhost:8080/api/
4. Authenticate by registering and/or logging in to get a JWT token.
5. Go to the Authorization tab.
6. Choose Bearer Token as the Auth Type.
7. Paste the JWT token you received into the token field to access all protected endpoints.