not-byte / basketball-api

Basketball team REST API serves as an essential extension to the team's website. Project is built around JavaScript (TypeScript 🌌) with Express framework (Node.js). It integrates technologies such as CockroachDB 🪳 and Socket.IO 📡.

botprzemek's Basketball API

[!Caution] > Project is still work in progress

Project Overview 📝

Stack of whole project including website project - CENN (CockroachDB, Express, Nuxt, NodeJS)

This documentation provides an overview of the REST API project developed for the Knury Knurów basketball team. The API is built around JavaScript (TypeScript 🌌) with Express ☕ framework (Node.js). It integrates technologies such as CockroachDB 🪳 and Socket.IO 📡, Node-Mailer 📫 and Node-Cache ✴️

Navigation 🚏

1. Status
2. Project Overview
3. Quick Start
4. Features
5. Usage
6. Technologies used
7. Endpoints
8. Database Models
9. Contributors
10. Author
11. License

Quick Start 🚀

Testing API instance running on this link, please refer to API's endpoints

1. Install Node

2. Clone repository git clone https://github.com/botprzemek/basketball-api.git

cd basketball-api

npm install

cp .env.example .env

setup env file

PORT=3000
ADDRESSES=["http://localhost:3001"]

SECRET=generated_secret

COCKROACH_HOST=your.database.domain.com
COCKROACH_PORT=26257
COCKROACH_NAME=api
COCKROACH_USER=your_user
COCKROACH_PASSWORD=your_database_password

MAIL_URL=your.mail.domain.com
MAIL_PORT=587
MAIL_USER=your_user
MAIL_PASSWORD=your_mail_password

TOKEN_KEY=generated_token

npm run dev

To run the project in development mode (Nodemon - Restarting after changes), execute the following command:

npm run dev

To run the seeding script to fill your database, execute the following command:

npm run seed

To run the project in production mode (PM2 - daemonize app and logging), execute the following command:

npm run server

Usage 🎉

Technologies Used 💡

1. JavaScript: Programming language used for the project's core functionality. 🧰
2. TypeScript: Superset of mentioned above JavaScript, used for adding static typing and enhancing code maintainability. 🔗
3. Node An asynchronous event-driven JavaScript runtime, designed to build scalable network applications. 🔮
4. CockroachDB: Database engine used for storing and retrieving team-related data. 📁
5. Express: Web application framework for building the API's routes and handling requests. 🖨️
6. Node-Cache: Caching mechanisms implemented using Node-Cache package to optimize API performance. 📦
7. Node-Mailer: Allows easy as cake email sending. 📫
8. Socket.IO: Caching mechanisms implemented using Node-Cache package to optimize API performance. 📦

Database Models 🧮

This section provides an overview of the structure, including basketball arenas, cities, players, teams, statistics, matches, and rosters, along with their respective relationships inside the CockroachDB database.

1. City

• id (INT8): Primary key, unique identifier for the city.
• name (VARCHAR): Name of the city (not null, unique).
• state (VARCHAR): State of the city (not null).

Indexes:

• name_idx: Index on the name column.

2. Arena

• id (INT8): Primary key, unique identifier for the arena.
• city_id (INT8): Foreign key referencing the city table (not null, references city.id, on delete cascade).
• name (VARCHAR): Name of the arena (not null, unique).
• location (VARCHAR): Location of the arena (not null).

Indexes:

• name_idx: Index on the name column.
• city_id_idx: Index on the city_id column.

3. League

• id (INT8): Primary key, unique identifier for the league.
• arena_id (INT8): Foreign key referencing the arena table (not null, references arena.id, on delete cascade).
• city_id (INT8): Foreign key referencing the city table (not null, references city.id, on delete cascade).
• name (VARCHAR): Name of the league (not null, unique).

Indexes:

• name_idx: Index on the name column.
• arena_id_idx: Index on the arena_id column.
• city_id_idx: Index on the city_id column.

4. Match

• id (INT8): Primary key, unique identifier for the match.
• arena_id (INT8): Foreign key referencing the arena table (not null, references arena.id, on delete cascade).
• league_id (INT8): Foreign key referencing the league table (not null, references league.id, on delete cascade).
• timestamp (TIMESTAMP): Timestamp of the match (not null, unique).

Indexes:

• timestamp_idx: Index on the timestamp column.
• arena_id_idx: Index on the arena_id column.
• league_id_idx: Index on the league_id column.

5. Team

• id (INT8): Primary key, unique identifier for the team.
• city_id (INT8): Foreign key referencing the city table (not null, references city.id, on delete cascade).
• league_id (INT8): Foreign key referencing the league table (not null, references league.id, on delete cascade).
• name (VARCHAR): Name of the team (not null, unique).
• won (INT8): Number of matches won by the team (not null, default 0).
• lost (INT8): Number of matches lost by the team (not null, default 0).

Indexes:

• name_idx: Index on the name column.
• city_id_idx: Index on the city_id column.
• league_id_idx: Index on the league_id column.

6. Staff

• id (INT8): Primary key, unique identifier for the staff.
• name (VARCHAR): First name of the staff (not null).
• lastname (VARCHAR): Last name of the staff (not null).
• role (role_enum): Role of the staff (not null).

Indexes:

• name_idx: Index on the name column.
• role_idx: Index on the role column.

7. Team_Staff

• staff_id (INT8): Foreign key referencing the staff table (not null, references staff.id, on delete cascade).
• team_id (INT8): Foreign key referencing the team table (not null, references team.id, on delete cascade).

Indexes:

• staff_id_idx: Index on the staff_id column.
• team_id_idx: Index on the team_id column.

8. Team_Statistics

• id (INT8): Primary key, unique identifier for the team statistics.
• match_id (INT8): Foreign key referencing the match table (not null, references match.id, on delete cascade, unique).
• team_id (INT8): Foreign key referencing the team table (not null, references team.id, on delete cascade).
• assists (INT8): Number of assists by the team.
• rebounds_off (INT8): Number of offensive rebounds by the team.
• rebounds_def (INT8): Number of defensive rebounds by the team.
• inside_fgm (INT8): Number of inside field goals made by the team.
• inside_fga (INT8): Number of inside field goals attempted by the team.
• outside_fgm (INT8): Number of outside field goals made by the team.
• outside_fga (INT8): Number of outside field goals attempted by the team.
• freethrows_fgm (INT8): Number of free throws made by the team.
• freethrows_fga (INT8): Number of free throws attempted by the team.
• blocks (INT8): Number of blocks by the team.
• steals (INT8): Number of steals by the team.
• turnovers (INT8): Number of turnovers by the team.
• fouls (INT8): Number of fouls by the team.

Indexes:

• match_id_idx: Index on the match_id column.
• team_id_idx: Index on the team_id column.

9. Quarter_Statistics

• id (INT8): Primary key, unique identifier for the quarter statistics.
• match_id (INT8): Foreign key referencing the match table (not null, references match.id, on delete cascade).
• team_id (INT8): Foreign key referencing the team table (not null, references team.id, on delete cascade).
• quarter (INT8): Quarter number.
• assists (INT8): Number of assists in the quarter.
• rebounds_off (INT8): Number of offensive rebounds in the quarter.
• rebounds_def (INT8): Number of defensive rebounds in the quarter.
• inside_fgm (INT8): Number of inside field goals made in the quarter.
• inside_fga (INT8): Number of inside field goals attempted in the quarter.
• outside_fgm (INT8): Number of outside field goals made in the quarter.
• outside_fga (INT8): Number of outside field goals attempted in the quarter.
• freethrows_fgm (INT8): Number of free throws made in the quarter.
• freethrows_fga (INT8): Number of free throws attempted in the quarter.
• blocks (INT8): Number of blocks in the quarter.
• steals (INT8): Number of steals in the quarter.
• turnovers (INT8): Number of turnovers in the quarter.
• fouls (INT8): Number of fouls in the quarter.

Indexes:

• match_id_idx: Index on the match_id column.
• team_id_idx: Index on the team_id column.

10. Roster

• id (INT8): Primary key, unique identifier for the roster.
• match_id (INT8): Foreign key referencing the match table (not null, references match.id, on delete cascade).
• team_id (INT8): Foreign key referencing the team table (not null, references team.id, on delete cascade).

Indexes:

• match_id_idx: Index on the match_id column.
• team_id_idx: Index on the team_id column.

11. Player

• id (INT8): Primary key, unique identifier for the player.
• team_id (INT8): Foreign key referencing the team table (not null, references team.id, on delete cascade).
• name (VARCHAR): First name of the player (not null).
• lastname (VARCHAR): Last name of the player (not null).
• number (INT8): Player number (not null, unique within a team).
• height (INT8): Height of the player (not null).
• position (position_enum): Position of the player (not null).
• birthday (DATE): Birthday of the player (not null).
• starter (BOOLEAN): Indicates if the player is a starter (default false).

Indexes:

• name_idx: Index on the name column.
• lastname_idx: Index on the lastname column.
• team_id_idx: Index on the team_id column.
• Unique constraint on (team_id, number).

12. Player_Roster

• player_id (INT8): Foreign key referencing the player table (not null, references player.id, on delete cascade).
• roster_id (INT8): Foreign key referencing the roster table (not null, references roster.id, on delete cascade).

Indexes:

• player_id_idx: Index on the player_id column.
• roster_id_idx: Index on the roster_id column.

13. Player_Statistics

• id (INT8): Primary key, unique identifier for the player statistics.
• match_id (INT8): Foreign key referencing the match table (not null, references match.id, on delete cascade).
• player_id (INT8): Foreign key referencing the player table (not null, references player.id, on delete cascade).
• minutes (INT8): Number of minutes played by the player.
• assists (INT8): Number of assists by the player.
• rebounds_off (INT8): Number of offensive rebounds by the player.
• rebounds_def (INT8): Number of defensive rebounds by the player.
• inside_fgm (INT8): Number of inside field goals made by the player.
• inside_fga (INT8): Number of inside field goals attempted by the player.
• outside_fgm (INT8): Number of outside field goals made by the player.
• outside_fga (INT8): Number of outside field goals attempted by the player.
• freethrows_fgm (INT8): Number of free throws made by the player.
• freethrows_fga (INT8): Number of free throws attempted by the player.
• blocks (INT8): Number of blocks by the player.
• steals (INT8): Number of steals by the player.
• turnovers (INT8): Number of turnovers by the player.
• fouls (INT8): Number of fouls by the player.

Indexes:

• match_id_idx: Index on the match_id column.
• player_id_idx: Index on the player_id column.
• Unique constraint on (match_id, player_id).

14. Backlog

• id (INT8): Primary key, unique identifier for the backlog.
• match_id (INT8): Foreign key referencing the match table (not null, references match.id, on delete cascade).
• data (VARCHAR): Backlog data (not null).
• timestamp (DATE): Timestamp of the backlog entry (not null, default current timestamp).

Indexes:

• match_id_idx: Index on the match_id column.

Endpoints 📡

Contributors

This project follows the all-contributors specification and is brought to you by these awesome contributors.

author

Github @botprzemek Discord botprzemek Email [e-mail]

license

This project is licensed under the terms of the Apache License 2.0

http2 protobuf