tokei-api
tokei-api
tokei-api is a web application that provides an API to retrieve source code from a specified Git repository, execute the tokei command, and return the results in JSON format. It also provides a web interface to visualize the code statistics.
Features
API
Core API
-
POST /api/analyses
- Analyzes the source code of a specified Git repository and returns the results in JSON{ "url": "https://github.com/kojix2/tokei-api.git" }
-
GET /api/analyses?url=...
- Retrieve cached analysis result by repository URL -
GET /api/analyses/:id
- Retrieves a specific analysis result with detailed information -
GET /api/analyses/:id/languages
- Retrieves language statistics for a specific analysis -
GET /api/analyses/:id/badges/:type
- Retrieves badge data for a specific analysis
GitHub-specific API
GET /api/github/:owner/:repo
- Analyzes a GitHub repository directlyGET /api/github/:owner/:repo/languages
- Retrieves language statistics for a GitHub repositoryGET /api/github/:owner/:repo/badges/:type
- Retrieves badge data for a GitHub repository
Badge API
GET /badge/github/:owner/:repo/:type
- Simplified URL for retrieving badge data in shields.io compatible format
Available badge types: lines
, language
, languages
, ratio
GET /api/badge/:type?url=...
- Retrieves badge data in shields.io compatible format for any Git repository
Web Interface
- Input repository URL on the home page for analysis
- Visualize results with graphs and tables
- View past analysis results
- Direct access to GitHub repositories via
/github/:owner/:repo
- Badge integration for READMEs
Installation
Requirements
Setup
-
Clone the repository
git clone https://github.com/kojix2/tokei-api.git cd tokei-api
-
Install dependencies
shards install
-
Set environment variables
cp .env.example .env # Edit the .env file to set database connection information and other settings
Key environment variables:
DATABASE_URL
: PostgreSQL connection stringDATABASE_PROVIDER
: Database provider (local or neon)TEMP_DIR
: Directory for temporary git clonesCLONE_TIMEOUT_SECONDS
: Timeout for git clone operations (default: 30)
-
Prepare the database
# Tables will be created automatically on first application startup
-
Start the application
crystal run src/tokei-api.cr
Usage
API Usage Examples
# Analyze a repository
curl -X POST -H "Content-Type: application/json" -d '{"url":"https://github.com/kojix2/tokei-api.git"}' http://localhost:3000/api/analyses
# Analyze a GitHub repository directly
curl http://localhost:3000/api/github/kojix2/tokei-api
# Retrieve language statistics
curl http://localhost:3000/api/github/kojix2/tokei-api/languages
# Get badge data
curl http://localhost:3000/badge/github/kojix2/tokei-api/lines
Badge Integration
You can add badges to your README to showcase your code statistics:
[](https://tokei.kojix2.net/github/username/repo)
[](https://tokei.kojix2.net/github/username/repo)
[](https://tokei.kojix2.net/github/username/repo)
[](https://tokei.kojix2.net/github/username/repo)
These badges are dynamic and will automatically reflect the latest analysis of your repository.
Web Interface
The web interface consists of several pages:
- Home page: Access http://localhost:3000 to enter a repository URL for analysis
- Results page: View detailed analysis with graphs and statistics
- API page: Documentation for the REST API endpoints
- Badges page: Information on how to integrate badges into your projects
For GitHub repositories, you can use the direct access URL format:
http://localhost:3000/github/owner/repo
For example: http://localhost:3000/github/kojix2/tokei-api
Development
# Run in development mode (auto-reload)
crystal run src/tokei-api.cr
Database Schema
The application uses a PostgreSQL database with the following schema:
CREATE TABLE analyses (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
repo_url TEXT NOT NULL,
analyzed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
result JSONB NOT NULL,
total_lines INTEGER,
total_code INTEGER,
total_comments INTEGER,
total_blanks INTEGER,
top_language TEXT,
top_language_lines INTEGER,
language_count INTEGER,
code_comment_ratio FLOAT
);
Deployment
Deploying to Koyeb
- Create a Koyeb account
- Create a new application
- Connect your GitHub repository
- Set environment variables (DATABASE_URL, etc.)
- Execute deployment
Running with Docker
Running in a single container
# Build Docker image
docker build -t tokei-api .
# Run container
docker run -p 3000:3000 --env-file .env tokei-api
Running with Docker Compose (recommended)
Docker Compose allows you to start the application and PostgreSQL database together.
# Build and start containers
docker compose up -d
# Check logs
docker compose logs -f
# Stop containers
docker compose down
# Completely remove including database volume
docker compose down -v
Switching environments
You can switch between local PostgreSQL and Neon by changing DATABASE_PROVIDER
in the .env
file:
# For local development (PostgreSQL in Docker Compose)
DATABASE_PROVIDER=local
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/tokei-api
# For Neon connection (when deploying to Koyeb)
# DATABASE_PROVIDER=neon
# DATABASE_URL=postgresql://username:password@hostname/database?sslmode=require
Technology Stack
- Language: Crystal
- Framework: Kemal
- Database: PostgreSQL (Neon)
- Frontend: Bootstrap, Chart.js
- Other: tokei, Git
License
Contributing
- Fork it (https://github.com/kojix2/tokei-api/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Author
- kojix2 - creator and maintainer
tokei-api
- 0
- 0
- 1
- 0
- 3
- 2 days ago
- March 20, 2025
MIT License
Fri, 04 Apr 2025 15:52:24 GMT