CBBD API

This is the repository for the CBBD API, currently hosted at api.CollegeBasketballData.com. The API is built on NodeJS using TypeScript and Express over a PostgreSQL database.

This project is an offshoot of CollegeFootballData.com. You can retrieve an API key at the CollegeBasketballData.com website that will work with both the CFBD and CBBD APIs.

Getting Started

This repo uses pnpm for dependency management. Run the following commands to install dependencies and start a dev server with hot reloading:

pnpm install
pnpm dev

Documentation commands use the generated TSOA OpenAPI document as their source:

pnpm docs:build    # generate OpenAPI and build the Zudoku site
pnpm docs:dev      # generate OpenAPI and start the Zudoku dev server

The deployed Zudoku documentation is served by the API application. The generated OpenAPI document remains available at /api-docs.json, and the previous Swagger UI remains available at /swagger during the transition.

CFB Website Service Containment

Production requires CFBD_PUBLIC_PAGE_SERVICE_USER_ID and CFBD_EXPORTER_SERVICE_USER_ID. These are distinct positive user IDs from the shared authentication database, not bearer tokens. The CBB API rejects both identities before recording request metrics so CFB website credentials cannot be reused against CBB endpoints.

Deploy this containment before activating the corresponding credentials in the CFB website. Remove it only as part of a separately approved CBB service- credential migration after both CFB credentials can no longer reach the CBB API.

Code Formatting

This repo uses prettier and eslint for code formatting. Run the following command to format your code before committing:

pnpm prettify

Semantic Versioning

Semantic versioning is used for this project. Version numbers are automatically updated via semantic-release based on commit messages. commitlint is used to enforce commit message formatting.

Project Architecture

tsoa and Express

This project uses tsoa to generate OpenAPI documentation and Express routes from TypeScript controllers.

Data Access

Data access is implemented using kysely, a lightweight SQL query builder for TypeScript.

Folder Structure

src/
├── app/ - application logic
│   └── category/ - application category
│       ├── controller.ts - tsoa controller
│       ├── service.ts - business logic
│       └── types.ts - typescript types
├── config/
│   ├── middleware/ - tsoa and express middlewares
│   ├── types/ - typescript types
│   ├── auth.ts - authorization logic
│   ├── database.ts - database configuration
│   ├── errors.ts - error handling
│   └── express.ts - express configuration
├── globals/ - global types and constants
└── app.ts - application entrypoint