GitHub Stars Badge API

A high-performance FastAPI service that generates dynamic GitHub star count badges and provides star count data via REST API. Perfect for README files, documentation, and dashboards.

Features

• High Performance: Async FastAPI with LMDB caching for lightning-fast responses
• Dual Output: JSON API for star counts + SVG badges for visual display
• Rate Limiting: Built-in protection against abuse with configurable limits
• Persistent Caching: LMDB-based storage reduces GitHub API calls
• Customizable Badges: Multiple themes and colors via shields.io
• GitHub Token Support: Higher rate limits with personal access token
• Real-time Data: Fetches live star counts from GitHub API

Quick Start

Installation

1. Clone the repository:

   git clone https://github.com/rawbytedev/github-stars-badge.git
   cd github-stars-badge

2. Install dependencies:

   pip install -r requirements.txt

3. Run the server:

   python -m src

The API will be available at http://localhost:8000

Docker (Not ready yet)

# When available:
docker build -t github-stars-badge .
docker run -p 8000:8000 github-stars-badge

API Documentation

Endpoints

Get User Star Count

GET /api/v1/stars/{username}

Response:

{
  "owner": "torvalds",
  "stars": 156789
}

Get Repository Star Count

GET /api/v1/stars/{owner}/{repo}

Response:

{
  "owner": "microsoft",
  "repo": "vscode",
  "stars": 145678
}

Get User Badge

GET /api/v1/badge/user/{username}?theme=flat

Returns an SVG badge showing total stars for the user.

Get Repository Badge

GET /api/v1/badge/repo/{owner}/{repo}?theme=flat

Returns an SVG badge showing stars for the specific repository.

Health Check

GET /api/v1/health

Response:

{
  "status": "healthy",
  "database": "connected"
}

Or if unhealthy:

{
  "status": "unhealthy",
  "database": "error",
  "error": "Database connection failed"
}

Parameters

Parameter	Type	Default	Description
theme	string	flat	Badge theme: flat, flat-square, for-the-badge, plastic

Rate Limits

• User badges: 10 requests/minute
• Repository badges: 10 requests/minute (cost: 2)
• Star counts: 10 requests/minute (cost: 2)

Usage Examples

In Markdown (README files)

User Total Stars

![GitHub Stars](https://img.shields.io/endpoint?url=https://your-domain.com/api/v1/badge/user/torvalds)

Repository Stars

![VS Code Stars](https://img.shields.io/endpoint?url=https://your-domain.com/api/v1/badge/repo/microsoft/vscode)

With Custom Theme

![Stars](https://img.shields.io/endpoint?url=https://your-domain.com/api/v1/badge/user/torvalds&theme=for-the-badge)

In HTML

<img src="https://your-domain.com/api/v1/badge/user/torvalds" alt="GitHub Stars" />

Programmatic Usage

Python

import requests

# Get star count
response = requests.get("http://localhost:8000/api/v1/stars/microsoft/vscode")
data = response.json()
print(f"VS Code has {data['stars']:,} stars")

# Get badge URL
badge_url = "http://localhost:8000/api/v1/badge/repo/microsoft/vscode?theme=flat-square"

JavaScript

// Fetch star count
fetch('http://localhost:8000/api/v1/stars/microsoft/vscode')
  .then(res => res.json())
  .then(data => console.log(`${data.stars} stars`));

// Use badge in HTML
const img = document.createElement('img');
img.src = 'http://localhost:8000/api/v1/badge/repo/microsoft/vscode';
document.body.appendChild(img);

cURL

# Get star count
curl http://localhost:8000/api/v1/stars/microsoft/vscode

# Get badge (returns SVG)
curl http://localhost:8000/api/v1/badge/repo/microsoft/vscode

Configuration

Environment Variables

Variable	Default	Description
GITHUB_TOKEN	None	GitHub personal access token for higher rate limits
CACHE_TTL	10	Cache lifetime in seconds before star counts are refreshed
RATE_LIMIT	10	Number of requests allowed per period
RATE_LIMIT_COST	2	Cost per request for rate limiting
RATE_LIMIT_PERIOD	minute	Time period for rate limiting (e.g., minute, hour)
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
DB_PATH	store.db	Path to LMDB database file
INDEX_PATH	index.db	Path to LMDB index file

Cache Refresh Behavior

Star counts are cached in LMDB under the user or owner/repo key. When a request arrives within CACHE_TTL seconds of the cached timestamp, the service returns the cached value without calling the GitHub API.

After the TTL expires, the next request treats the value as stale, fetches a fresh star count from GitHub, and writes the updated value back to the cache. No background refresh job runs automatically, so refreshes happen on demand. To use a longer cache window, set CACHE_TTL in the runtime environment, for example CACHE_TTL=600 for ten minutes.

GitHub Token Setup

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate a new token with public_repo scope
3. Set environment variable: export GITHUB_TOKEN=your_token_here
4. Restart the server

Benefits: Increases rate limit from 60 to 5000 requests/hour.

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FastAPI App   │───▶│   LMDB Cache    │───▶│  GitHub API     │
│                 │◀───│   (Persistent)  │◀───│  (Live Data)    │
│ • Rate Limiting │    │ • Fast Lookup   │    │ • Star Counts    │
│ • Error Handling│    │ • TTL Support   │    │ • Rate Limited   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Components

• FastAPI: Modern async web framework
• httpx: Async HTTP client for GitHub API
• LMDB: Lightning-fast embedded database
• slowapi: Rate limiting middleware
• shields.io: Badge generation service

Development

Setup Development Environment

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run with auto-reload
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Testing

Run the test suite:

pytest

Linting

Run linting:

pylint src/ --rcfile=.pylintrc
black --check src/
mypy src/

Project Structure

github-stars-badge/
├── src/
│   ├── __init__.py      # Package initialization
│   ├── __main__.py      # Entry point for python -m src
│   ├── main.py          # FastAPI application
│   ├── config.py        # Configuration constants
│   ├── models.py        # Pydantic models
│   ├── services.py      # GitHub service layer
│   ├── utils.py         # Utility functions
│   ├── dbmanager.py     # Database management utilities
│   └── storage/
│       ├── __init__.py  # Storage package
│       ├── db.py        # LMDB database wrapper
│       └── hashcrypto.py # Hashing utilities
├── tests/               # Test suite
│   ├── conftest.py      # Pytest configuration
│   ├── test_api.py      # API endpoint tests
│   ├── test_caching.py  # Caching functionality tests
│   └── test_github.py   # GitHub API integration tests
├── requirements.txt     # Python dependencies
├── requirements-dev.txt # Development and quality-check dependencies
└── README.md           # This file

Contributing

Contributions are welcome. See CONTRIBUTING.md for local setup, code standards, test commands, commit guidance, and the pull request checklist.

Notable user-facing changes are tracked in CHANGELOG.md.

Testing

Run the test suite:

pytest

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.

Acknowledgments

• FastAPI - Modern async web framework
• shields.io - Beautiful badge generation
• LMDB - High-performance database
• GitHub API - Star count data source

Support

• Email: [radiationbolt@gmail.com]
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the open source community