CMSC 22000 Final report

Quarter: Spring 2025

Feature: API

Design and Implementation

Collab with Achievements team

This work consisted of implementing API endpoints for the Achievements and Game Management team. The main goals were to support their core functionalities (retrieving and creating Achievement/Game-related objects) to set the foundation for future use. These endpoints will become useful for future frontend implementation of the features created by these teams.

Achievement endpoints

These endpoints were created to allow the Achievements team to define and manage achievements tied to individual games. Functionalities include creating new Achievement objects, obtaining a list of existing Achievement objects for a particular game, and updating existing Achievement objects. These endpoints rely on the Achievement model created by the Achievements team, and the Achievement serializer created by the API team. Testing for these endpoints has been implemented in the tests folder for the API team, and these tests are reliant on various Django factories (Achievement, User, Game, etc) made available by the API team.

User Achievement endpoints

These endpoints were created to allow the Achievements team to define and manage user achievements tied to individual games. Functionalities include creating new UserAchievement objects by assigning existing Achievement objects to users, obtaining a list of existing Achievement objects obtained by a given user, and updating existing UserAchievement objects. These endpoints rely on both the Achievement UserAchievement models created by the Achievements team, and the UserAchievement serializer created by the API team. Testing for these endpoints has been implemented in the tests folder for the API team, and these tests are reliant on various Django factories (UserAchievement, Achievement, User, Game, etc) made available by the API team.

Game Review endpoints

These endpoints were created to allow the Game management team to define and manage game reviews tied to individual games. Functionalities include creating new GameReview objects, obtaining a list of existing GameReview objects for a particular, and updating existing GameReview objects. These endpoints rely on the Review model created by the Game management team, and the GameReview serializer created by the API team. Testing for these endpoints has been implemented in the tests folder for the API team, and these tests are reliant on various Django factories User, Game, etc) made available by the API team.

For future developers

At this time, the above endpoints lack comprehensive documentation. However, developers are strongly encouraged to review the GitHub pull requests related to each endpoint, which include implementation details and test cases that offer clear insight into how they work. In addition, while the current set of endpoints supports core achievement and game review functionality, there is room to add more endpoints for added functionality. Future developers are encouraged to implement additional endpoints as these features grow. Lastly, it is worth noting that the implementation logic of these endpoints is tightly coupled to the structure of the corresponding models (Achievement, UserAchievement, Game, Review). Changes to any of these models may break endpoint functionality. Developers modifying the models must revisit and update views, serializers, and tests accordingly.

Collab with leaderboards/word game team

This work consisted of implementing API endpoints for the leaderboards and word game team. The main goals were to support their core functionalities (retrieving and creating Leaderboard/GameData objects) to set the foundation for future use.

Word Game Features

The Word Game team undertook the task of implementing the GameData components for ChiGame – the core value-add being the ability for games to now store temporary states associated with players’ accounts. These features rely solely on the GameData models and serializers as defined in the api folder and they interact with existing models (User, UserProfiles, etc).

Leaderboard Features

Our team focused on implementing the bare features for the leaderboards. Due to the leaderboard objects being very heavily reliant on existing chigame models, it was difficult to iteratively review and test endpoints on the fly alongside the changes being made by other teams. The core functionalities are working – chigame users are able to post a score to a leaderboard for a game (given that these objects exist) and should be able to retrieve the all-time leaderboard given a game id.

For Future Developers

Authentication using the Leaderboard endpoints means that developers may have to use SessionAuthentication when posting and retrieving scores. This was an additional layer of authentication added, but is a high-priority item; removing this feature would not hamper the functionality of the endpoints in any way. Please refer to the Leaderboard wiki to continue implementing more of their endpoints.

Collab with live chats/tournaments

This work focused on adding and improving backend features for the LiveChat and Tournament components in ChiGame. The main goals were to build APIs that support chat functionality, tournament feedback, and simulation of tournament brackets.

LiveChat Features

A set of API endpoints was created to support key LiveChat functionality, including creating chats, viewing chats a user is part of, adding users to a chat, and retrieving detailed information about a chat. These rely on the LiveChat, LiveChatUser, and User models. Membership is handled through LiveChatUser, which keeps track of who is in each chat and makes it easier to expand features later (e.g., roles or permissions). The endpoints were designed to be flexible. For example, a tournament could create a LiveChat automatically when it starts, allowing players to coordinate in real time. The list endpoint only returns chats the authenticated user is in, which is useful for displaying user-specific chat histories on the frontend. Testing was done using Django REST Framework’s testing tools and factory_boy for generating test data. The test suite covers all main use cases and uses force_authenticate to simulate logged-in users.

Tournament Simulation and Feedback

An API endpoint was also added for simulating tournament brackets. This feature builds on existing tournament logic and lets users preview how a bracket would look, using either single or double elimination. The simulation runs entirely in memory and doesn’t affect the database, so it is a safe way to test different configurations. In addition, a simple feedback system for tournaments was implemented. This includes endpoints for creating, updating, and deleting feedback, as well as listing all feedback for a given tournament. The feedback model is tied directly to the Tournament model, and the system was designed with DRF permission classes in mind. All the live chat and tournaments features depend on shared models like User, Tournament, and Lobby and were designed to work alongside existing systems without major changes. The LiveChat features are especially relevant to the frontend and tournament teams, who may want to integrate chat into their user flows.

Notes for Future Developers

The LiveChatUser model is a good starting point for any changes involving chat membership or roles. For simulations, tournament simulation is read-only and doesn’t save results. Saving simulations would require writing logic to create and store matches and lobbies. For testing, all test files are set up using factory_boy and follow a consistent structure for API testing. And to restore authentication, DRF permissions can be re-enabled easily, since the view classes were written with that in mind.

Collab with Game Management Team

This work consisted of implementing API endpoints that support the Game Management team’s features, including retrieving game metadata for dynamic UI components and providing review-based statistics such as average rating and popularity. These endpoints were important to enabling frontend functionality.

Game Pop-up Metadata Endpoint

To support the new hover-based UI in the Game Browser, we implemented a dedicated endpoint at GET /api/games/{game_id}/popups/. This endpoint returns concise metadata, such as minimum and maximum number of players, complexity, minimum and maximum playtime, and a short description, specifically tailored for pop-up previews in the frontend. It allows the client to dynamically render lightweight game summaries without fetching the entire game object. Unit tests were written in test_popups.py to ensure that the endpoint returns the correct structure for valid games and handles edge cases appropriately. These tests confirm that a valid game returns a 200 response, while nonexistent games return a 404, and disallowed HTTP methods like POST yield a 405 response.

Review Statistics Features

Another key endpoint we developed was GET /api/games/{id}/review-stats/, which returns the average rating and popularity of a game based on public reviews. These statistics are integrated into the Game Management UI to display community sentiment and engagement metrics. The endpoint is designed to handle several edge cases. If no public reviews exist, the popularity is reported as zero. If public reviews exist but none include a rating, the average rating is returned as null. Additionally, private reviews are excluded from all calculations. We introduced comprehensive unit tests in test_review_stats.py to verify correct behavior across these scenarios, as well as to confirm that invalid game IDs return a 404 and unsupported methods result in a 405.

Next Steps

At the beginning of the quarter, our team took on an existing task Creating API endpoint to send/accept friend requests leftover from the previous year which sought to implement an endpoint to allow users to send and accept friend requests/invitations. Our team was not able to address this issue because we found that it involves an error in functionality with one of the models from the Users team that they had not addressed this quarter. We encourage future API developers to further collaborate with the team responsible for User-related objects to address this issue.

Leaderboards team still has existing endpoints that can be integrated. We have implemented the basic POST and GET endpoints, but many of the remaining endpoints are left to be implemented. This also means that there are a suite of tests that can be written for the Leaderboard endpoints (including the existing POST and GET endpoints). Separately, there are existing issues that can be written related to enhancing the existing GameData API endpoints (pagination and ordering, advanced filtering).

The spam filtering system for LiveChats and Tournaments could be a good task to improve upon. Right now, users can post anything, and there’s no way to filter out low-effort or repetitive messages. A simple rule-based system (like rate limits or detecting repeated messages) already exists, but we can expand the coverage in spam_utils.py ton include other databases or spam mechanisms. There’s also room to try more advanced approaches like keyword matching or basic text analysis. Once a spam filter is in place, it should be connected to the LiveChat message feed so that users only see relevant messages. Over time, this system could also tie into the tournament recommendation feature (an API endpoint has not been created yet), such as highlighting tournaments with active and high-quality chats. That way, players are more likely to find events with real engagement.

Another natural next step is to continue implementing API support for several of the Game Management team’s newly developed frontend features. These include exposing metrics that track when a game is searched, endpoints for users to create and manage custom lists of games, support for maintaining personal game queues, and functionality to power a recommendation system based on user behavior or preferences. While much of the frontend work for these features is already in place, the backend still requires dedicated endpoints, serializers, and models in some cases. Building out these APIs would allow the Game Management UI to evolve into a more personalized, interactive, and data-driven experience for users. Future teams should coordinate closely with the Game Management team to clarify data needs and ensure seamless integration.

There is an open pull request to create more API testing for all of the models implemented in ChiGame. That would be a simple place to get started with familiarizing oneself with the codebase. Even testing the serializers would be a good place to start to have an automated method of verifying the accurate format. The Knowledge Base and Interactive Fiction teams need more fleshed out API support as well, so starting there would be good idea as well.