GitHub Repository Search API

A Spring Boot application that provides APIs to search and manage GitHub repositories with rate limiting functionality.

Prerequisites

• Java 17 or higher
• Maven
• PostgreSQL
• Git

Setup and Installation

1. Clone the repository:

git clone <repository-url>
cd githubreposearch

2. Configure PostgreSQL:

• Create a PostgreSQL database
• Update application.properties with your database credentials:

spring.datasource.url=jdbc:postgresql://localhost:5432/your_database
spring.datasource.username=your_username
spring.datasource.password=your_password

3. Build and run the application:

mvn clean install
mvn spring:boot run

The application will start on port 8091.

API Documentation

1. Search Repositories

Searches GitHub repositories and saves them to the database.

Endpoint: POST /api/github/search Content-Type: application/json

Request Body:

{
    "query": "spring boot",
    "language": "java",
    "sort": "stars"
}

sort is optional: can be stars, forks, or updated

Response:

{
    "message": "Repositories fetched and saved successfully",
    "repositories": [
        {
            "id": 1234567,
            "name": "repository-name",
            "description": "Repository description",
            "owner": "owner-name",
            "language": "Java",
            "starsCount": 1000,
            "forks": 500,
            "lastUpdated": "2024-03-20T12:00:00"
        }
    ]
}

2. Retrieve Repositories

Retrieves repositories from the database with optional filters.

Endpoint: GET /api/github/repositories

Query Parameters:

• language (optional): Filter by programming language
• minStars (optional): Minimum number of stars
• sort (optional): Sort by "stars", "forks", or "updated" (default: stars)

Example Request:

GET /api/github/repositories?language=java&minStars=1000&sort=stars

Response:

[
    {
        "id": 1234567,
        "name": "repository-name",
        "description": "Repository description",
        "owner": "owner-name",
        "language": "Java",
        "starsCount": 1000,
        "forks": 500,
        "lastUpdated": "2024-03-20T12:00:00"
    }
]

Rate Limiting

The API implements rate limiting using Bucket4j:

• Default capacity: 5 requests
• Refill rate: 1 token per second

When rate limit is exceeded, the API returns:

• Status: 429 (Too Many Requests)
• Response includes retry-after information

Error Handling

The API returns appropriate HTTP status codes:

• 200: Successful operation
• 400: Bad request (invalid parameters)
• 429: Rate limit exceeded
• 500: Internal server error

Testing

Run the tests using:

mvn test

Database Schema

The application uses a repositories table with the following structure:

CREATE TABLE repositories (
id BIGINT PRIMARY KEY,
name VARCHAR(500) NOT NULL,
description TEXT,
owner VARCHAR(255) NOT NULL,
language VARCHAR(50),
stars_count INT DEFAULT 0,
forks_count INT DEFAULT 0,
last_updated TIMESTAMP NOT NULL
);


-- Create index for language field
CREATE INDEX idx_repository_language ON repositories (language);

-- Create index for stars count
CREATE INDEX idx_repository_stars_count ON repositories (stars_count DESC);

-- Create index for forks count
CREATE INDEX idx_repository_forks ON repositories (forks_count DESC);

-- Create index for last updated
CREATE INDEX idx_repository_last_updated ON repositories (last_updated DESC);

-- Create composite index for common filter combinations
CREATE INDEX idx_repository_language_stars ON repositories (language, stars_count DESC);

Logging

The application uses SLF4J for logging with the following levels:

• Root: DEBUG
• Spring Web: DEBUG
• Application Package: TRACE
• HTTP Processor: TRACE