{"id":31287759,"url":"https://github.com/sonii-shivansh/api-rate-limiter","last_synced_at":"2026-04-12T15:32:34.706Z","repository":{"id":312687545,"uuid":"1048336796","full_name":"sonii-shivansh/api-rate-limiter","owner":"sonii-shivansh","description":"A distributed, high-throughput API Rate Limiter built with Java, Spring Boot, and Redis. Uses the Token Bucket algorithm for efficient, scalable request throttling in a microservices architecture.","archived":false,"fork":false,"pushed_at":"2025-09-17T14:27:43.000Z","size":195,"stargazers_count":0,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T15:49:27.087Z","etag":null,"topics":["api-rate-limiter","docker","docker-compose","good-first-issue","hacktoberfest","java","k6","maven","microservices","redis","resilience4j","spring-boot","token-bucket"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonii-shivansh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T09:37:10.000Z","updated_at":"2025-09-17T14:29:35.000Z","dependencies_parsed_at":"2025-09-17T15:35:47.843Z","dependency_job_id":null,"html_url":"https://github.com/sonii-shivansh/api-rate-limiter","commit_stats":null,"previous_names":["sonii-shivansh/api-rate-limiter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sonii-shivansh/api-rate-limiter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonii-shivansh%2Fapi-rate-limiter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonii-shivansh%2Fapi-rate-limiter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonii-shivansh%2Fapi-rate-limiter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonii-shivansh%2Fapi-rate-limiter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonii-shivansh","download_url":"https://codeload.github.com/sonii-shivansh/api-rate-limiter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonii-shivansh%2Fapi-rate-limiter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276737524,"owners_count":25695700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rate-limiter","docker","docker-compose","good-first-issue","hacktoberfest","java","k6","maven","microservices","redis","resilience4j","spring-boot","token-bucket"],"created_at":"2025-09-24T11:08:03.355Z","updated_at":"2026-04-12T15:32:34.699Z","avatar_url":"https://github.com/sonii-shivansh.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# High-Throughput API Rate Limiter\n\nThis project implements a distributed, high-performance API rate limiter designed to protect backend services from traffic bursts and ensure fair usage. Built with a modern Java stack, it leverages Redis for high-speed, distributed state management and employs the **Token Bucket algorithm** for scalable and efficient request throttling.\n\nThe system is architected as a set of independent microservices orchestrated with Docker, featuring a central API Gateway that seamlessly integrates the rate-limiting logic.\n\n## System Architecture\n\nThe architecture consists of four main components that work together to process and rate-limit incoming requests:\n\n1.  **API Gateway**: The single entry point for all client requests. It forwards traffic to the Rate Limiter Service for authorization before proxying it to the appropriate backend service.\n2.  **Rate Limiter Service**: The core of the system. It applies the token bucket algorithm using a Redis-backed Lua script to ensure atomic operations, checking if an incoming request from a specific IP address is within the defined limits.\n3.  **Product Service**: A mock backend service representing a protected resource. It only receives requests that have been successfully authorized by the Rate Limiter Service.\n4.  **Redis**: An in-memory data store used to maintain the state of the token buckets for each client IP address in a distributed and highly available manner.\n\n```mermaid\ngraph TD\n    subgraph \"Client\"\n        A[User Request]\n    end\n\n    subgraph \"System Boundary\"\n        A --\u003e B(API Gateway);\n        B --\u003e C{Rate Limiter Service};\n        C -- Allowed --\u003e D[Product Service];\n        C -- Denied --\u003e B;\n        B -- 429 Too Many Requests --\u003e A;\n        D -- 200 OK with Data --\u003e C;\n        C --\u003e B;\n        B -- 200 OK with Data --\u003e A;\n        C \u003c--\u003e E[(Redis)];\n    end\n\n    style B fill:#26A69A,stroke:#004D40,stroke-width:2px,color:#fff\n    style C fill:#5C6BC0,stroke:#1A237E,stroke-width:2px,color:#fff\n    style D fill:#66BB6A,stroke:#1B5E20,stroke-width:2px,color:#fff\n    style E fill:#EF5350,stroke:#B71C1C,stroke-width:2px,color:#fff\n```\n\n## **Key Features**\n\n* **Microservices Architecture:** Decoupled services (Gateway, Rate Limiter, Product Service) for independent scaling and development.  \n* **Token Bucket Algorithm:** Implemented for efficient and flexible rate limiting that allows for bursts of traffic.  \n* **Distributed \u0026 Scalable:** Uses Redis as a centralized, high-speed data store, ensuring consistent rate limiting across multiple service instances.  \n* **Atomic Operations:** Employs a Redis LUA script to ensure that checking and consuming tokens is an atomic operation, preventing race conditions.  \n* **Resilient \u0026 Fault-Tolerant:** Integrates **Resilience4j** for Circuit Breaker and Retry patterns, ensuring the system can handle Redis connection failures gracefully.  \n* **Containerized \u0026 Composed:** Fully containerized with Docker and orchestrated with Docker Compose for easy, reproducible deployments.  \n* **Automated CI/CD:** Features GitHub Actions for continuous integration, automating the build, unit testing, and performance testing for every pull request.\n\n## **Technology Stack**\n\n* **Backend**: Java 21, Spring Boot 3, Project Reactor (WebFlux)\n* **API Gateway**: Spring Cloud Gateway\n* **Database**: Redis (for distributed state management)\n* **Build Tool**: Maven\n* **Containerization**: Docker, Docker Compose\n* **CI/CD**: GitHub Actions for automated building and testing\n* **Load Testing**: k6\n\n\n## **Performance Benchmark**\n\nThe system was load-tested using **k6**, simulating a ramp-up to **100 virtual users** over 30 seconds and sustaining that load for one minute. The results demonstrate the system's high throughput and low latency.\n\n* **Average Throughput: 79.40 requests/second**\n* **Average Latency (http_req_duration): 10.27ms**\n* **95th Percentile Latency: 17.75ms**\n* **Success Rate: 100%** (all requests correctly returned either a ```200 OK``` or ```429 Too Many Requests```)\n\nThese metrics confirm that the rate limiter adds minimal overhead while effectively enforcing usage policies under significant load.\n\n## **Getting Started**\n\n### **Prerequisites**\n\n* Git  \n* Docker \u0026 Docker Compose\n* Java 21 \n* Maven\n\n### **Running with Docker (Recommended)**\n\nThis is the easiest way to get all services up and running.\n\n1. **Clone the repository:**\n\n```\ngit clone https://github.com/sonii-shivansh/api-rate-limiter.git\ncd api-rate-limiter\n```\n\n2. **Build and run the services using Docker Compose:**\n\n```\ndocker-compose up --build -d\n```\nThis command will build the images for all services and start them in detached mode.\n\n### **Running Locally (Without Docker)**\n\n1. **Start Redis:**\nYou still need Redis running. You can start it easily with Docker:\n\n```\ndocker run --name my-redis -p 6379:6379 -d redis\n```\n\n2. Run each service:\nOpen three separate terminals and run the following command in each respective service directory (api-gateway, rate-limiter-service, product-service):\n\n```\n# Terminal 1: Product Service\ncd product-service\n./mvnw spring-boot:run\n\n# Terminal 2: Rate Limiter Service\ncd rate-limiter-service\n./mvnw spring-boot:run\n\n# Terminal 3: API Gateway\ncd api-gateway\n./mvnw spring-boot:run\n```\n\n## **Configuration**\n\nThe rate limit parameters can be easily configured in the ``` rate-limiter-service/src/main/resources/application.yml ``` file:\n\n```\nrate-limiter:\n  bucket-capacity: 10         # Max tokens in the bucket\n  refill-rate-per-minute: 10  # Tokens to add per minute\n```\nWith the default settings, each IP address is allowed 10 requests per minute.\n\n\n### Configure via Environment Variables (Recommended for Containers)\n\nYou can override the same properties via environment variables using Spring Boot's relaxed binding.\n\n- Use these environment variables for the Rate Limiter Service:\n  - `RATE_LIMITER_BUCKET_CAPACITY`\n  - `RATE_LIMITER_REFILL_RATE_PER_MINUTE`\n\nThese map to the YAML properties `rate-limiter.bucket-capacity` and `rate-limiter.refill-rate-per-minute` respectively. Spring automatically converts underscores to dots and respects kebab-case.\n\nExample Docker Compose snippet (already configured in this repo):\n\n```\nrate-limiter-service:\n  build: ./rate-limiter-service\n  environment:\n    - RATE_LIMITER_BUCKET_CAPACITY=10\n    - RATE_LIMITER_REFILL_RATE_PER_MINUTE=10\n    - SPRING_DATA_REDIS_HOST=my-redis\n```\n\nYou can change the values (e.g., `RATE_LIMITER_BUCKET_CAPACITY=100` and `RATE_LIMITER_REFILL_RATE_PER_MINUTE=60`) without modifying the application code or the `application.yml`.\n\n\n## API Endpoint \u0026 Testing\nOnce the services are running, you can test the rate limiter by making requests to the protected endpoint through the API Gateway.\n* **URL**: ```http://localhost:8080/api/products```\n* **Method**: ```GET```\n\nYou can use ```curl``` to test it. The first 10 requests within a minute should succeed. Subsequent requests will be rejected with a ```429 Too Many Requests``` status code until the token bucket is refilled.\n```\n# This request should succeed (if tokens are available)\ncurl -i http://localhost:8080/api/products\n\n# Run this 11 times in a loop to see the rate limit in action\n1..11 | ForEach-Object { curl http://localhost:8080/api/products }\n```\n\n## Contributing\n\nWe welcome contributions from the open-source community! If you're looking to contribute, please read our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.\n\nWe have a number of [\"good first issues\"](https://github.com/sonii-shivansh/api-rate-limiter/labels/good%20first%20issue) that are perfect for new contributors. We're excited to see your pull requests!\n\n## Project Roadmap\n\nHere are some of the features and improvements we have planned for the future.\n\n* **Implement Different Rate-Limiting Algorithms**: Add support for other algorithms like Sliding Window Log.\n* **Configuration via Environment Variables**: Allow rate limit values to be configured through environment variables for more flexible deployments.\n* **Enhanced Monitoring and Metrics**: Integrate with Prometheus and Grafana to provide a dashboard for visualizing rate-limiting metrics.\n* **Support for Authenticated Users**: Extend the rate-limiting logic to support different limits for authenticated vs. anonymous users.\n* **More Granular Rate Limits**: Allow for different rate limits based on API endpoints.\n\nWe're open to new ideas! If you have a suggestion, please open an issue to discuss it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonii-shivansh%2Fapi-rate-limiter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonii-shivansh%2Fapi-rate-limiter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonii-shivansh%2Fapi-rate-limiter/lists"}