Skip to content

BADGE_API.md

Latest commit

 

History

History
178 lines (125 loc) · 4.64 KB

BADGE_API.md

File metadata and controls

178 lines (125 loc) · 4.64 KB
Raw

CodeStride Badge API Documentation

Overview

The CodeStride Badge API provides public, shareable SVG badges that contributors can embed in their GitHub README to showcase their CodeStride statistics.

Endpoints

1. Streak Badge

Endpoint: GET /api/badge/streak?user=<githubLogin>

Returns an SVG badge displaying the user's current commit streak.

Query Parameters:

  • user (required): GitHub username

Example:

GET /api/badge/streak?user=octocat

Response:

  • Content-Type: image/svg+xml;charset=utf-8
  • SVG showing current streak (orange if active, indigo if none)
  • Cached for 1 hour

2. Commits Badge

Endpoint: GET /api/badge/commits?user=<githubLogin>

Returns an SVG badge displaying commits made this month.

Query Parameters:

  • user (required): GitHub username

Example:

GET /api/badge/commits?user=octocat

Response:

  • Content-Type: image/svg+xml;charset=utf-8
  • SVG showing commits count for current month
  • Cached for 1 hour

Usage

Markdown Embedding

Add to your GitHub README:

<!-- Streak Badge -->
![CodeStride Streak](https://codestride.app/api/badge/streak?user=yourname)

<!-- Commits Badge -->
![CodeStride Commits](https://codestride.app/api/badge/commits?user=yourname)

<!-- Both Together -->
![CodeStride Streak](https://codestride.app/api/badge/streak?user=yourname) ![CodeStride Commits](https://codestride.app/api/badge/commits?user=yourname)

Features

  • Public Access: No authentication required
  • Real-time Data: Fetches live data from GitHub API
  • Caching: Responses cached for 1 hour to reduce API load
  • No Auth Required: Uses publicly available GitHub data
  • Responsive: Dynamically sized based on content
  • Accessible: Includes proper SVG labels and titles

Color Scheme

  • Streak (Active): #f59e0b (Orange - active streak)
  • Streak (Inactive): #6366f1 (Indigo - no active streak)
  • Commits: #6366f1 (Indigo - CodeStride primary)
  • Error: #ef4444 (Red)

Response Headers

All badge endpoints return appropriate caching headers:

Content-Type: image/svg+xml;charset=utf-8
Cache-Control: max-age=3600, public
X-Content-Type-Options: nosniff

Error Handling

  • Missing user parameter: Returns 400 Bad Request
  • Invalid username: Returns 400 Bad Request
  • User not found: Returns SVG badge with "N/A" value
  • API errors: Returns SVG badge with "Error" value

Rate Limiting

  • The CodeStride badge API itself has no rate limits
  • However, it uses GitHub API internally, which may have rate limits
  • GitHub API: 60 requests/hour (unauthenticated), 5000/hour (authenticated)
  • Using GITHUB_TOKEN environment variable increases rate limits

Performance

  • Badge generation is fast (typically <200ms)
  • SVG is optimized for web delivery
  • Caching significantly reduces load on GitHub API
  • Badges are approximately 2-5KB in size

Getting Your Badge

  1. Go to your public CodeStride profile: https://codestride.app/u/yourname
  2. Scroll to "Get Your Badge" section
  3. Copy the markdown for your desired badge(s)
  4. Paste into your GitHub README
  5. Commit and push to your repository

Technical Details

Badge Generation

Badges use a shields.io-style design implemented with SVG:

  • Linear gradient background for depth
  • White text with subtle shadow
  • Rounded corners for modern appearance
  • Responsive sizing based on content

Data Sources

  • Streak badge: GitHub API commit search (last 90 days)
  • Commits badge: GitHub API commit search (current month)

Implementation

  • Built with Next.js API routes
  • Uses Supabase for user verification
  • Dynamically generates SVG content
  • Server-side caching with HTTP headers

Customization

To use a different domain:

![CodeStride Streak](https://your-domain.com/api/badge/streak?user=yourname)

Replace your-domain.com with your CodeStride deployment domain.

Support

For issues or feature requests related to badges:

  1. Check the CodeStride documentation
  2. Create an issue on GitHub
  3. Contact the CodeStride team

Examples

Single Badge

![CodeStride Streak](https://codestride.app/api/badge/streak?user=octocat)

Multiple Badges

[![CodeStride Streak](https://codestride.app/api/badge/streak?user=octocat)](https://codestride.app/u/octocat)
[![CodeStride Commits](https://codestride.app/api/badge/commits?user=octocat)](https://codestride.app/u/octocat)

With Profile Link

[
  ![CodeStride Streak](https://codestride.app/api/badge/streak?user=octocat)
](https://codestride.app/u/octocat)

GSSoC Badge API Rate Limiting

  • Badge requests are restricted to 100 per minute per IP.