Skip to main content

API Gateway

A unified API Gateway and Eureka Service Discovery solution for microservices architecture. This service combines API routing capabilities with service registry and dynamic discovery, providing centralized management for all Rippler microservices.

Architecture Diagram​

The following diagram illustrates the internal architecture of the API Gateway service, showing how requests flow through the gateway, how services register with Eureka, and how load balancing is performed.

Update the Architecture Diagram

To view and edit the architecture diagram:

  1. Open /docs/architecture/services/api-gateway.drawio in diagrams.net or VS Code with the Draw.io extension
  2. The diagram shows the flow of requests from clients through Spring Cloud Gateway, Eureka service discovery, load balancing, and routing to backend microservices
  3. After making changes, export to HTML and copy to /website/static/architecture/services/api-gateway.drawio.html

Overview​

The API Gateway serves as the entry point for all client requests and provides:

  • Unified API routing to backend services
  • Service discovery and registration via Eureka
  • Load balancing across service instances
  • Health monitoring and status tracking
  • Service change auditing

Features​

  • API Gateway: Routes incoming requests to appropriate microservices with load balancing
  • Eureka Service Discovery: Service registration and dynamic discovery
  • Service Change Tracking: Audit trail for all service lifecycle events
  • Health Monitoring: Built-in health checks and monitoring endpoints
  • Dynamic Routing: Automatic route discovery based on service registrations
  • Extensible Architecture: Ready for future billing and analytics capabilities

Technology Stack​

  • Java 17: Modern Java runtime
  • Spring Boot 3.x: Enterprise application framework
  • Spring Cloud Gateway: Reactive API gateway
  • Netflix Eureka: Service discovery and registration
  • Spring WebFlux: Reactive web framework
  • Maven: Build and dependency management

Quick Start​

Prerequisites​

  • Java 17 or higher
  • Maven 3.6+

Build and Run​

# Clone the repository
git clone https://github.com/Citi-Rippler/rippler-api-gateway.git
cd rippler-api-gateway

# Build the project
mvn clean package

# Run the application
mvn spring-boot:run

The API Gateway will start on http://localhost:8761

Access Points​

API Endpoints​

Service Management​

Get All Registered Services​

GET /api/services

Returns a list of all services registered with Eureka.

Response:

{
  "services": [
    {
      "name": "webhook-handler",
      "status": "UP",
      "instances": 1,
      "lastUpdated": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Service Change History​

GET /api/services/changes

Returns audit trail of all service registration events.

Response:

{
  "changes": [
    {
      "serviceId": "webhook-handler",
      "event": "REGISTERED",
      "timestamp": "2024-01-15T10:30:00Z",
      "metadata": {}
    }
  ]
}

Gateway Routing​

Get Active Routes​

GET /actuator/gateway/routes

Returns all active gateway routes.

Health Check​

Service Health​

GET /actuator/health

Returns the health status of the gateway and connected services.

Usage​

Registering a Service​

To register your service with the API Gateway:

  1. Add Eureka client dependency to your service:
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
  1. Configure your service's application.yml:
spring:
  application:
    name: my-service

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true
  1. Start your service - it will automatically register with Eureka

Accessing Services Through Gateway​

Once a service is registered, access it via the gateway:

http://localhost:8761/{service-name}/{endpoint}

Example:

# Access webhook handler
curl http://localhost:8761/webhook-handler/api/v1/webhooks

# Access LLM service
curl http://localhost:8761/llm-service/api/v1/analyze

Monitoring Service Changes​

Track all service registration events:

# Get all registered services
curl http://localhost:8761/api/services

# Get change history
curl http://localhost:8761/api/services/changes

Configuration​

Environment Variables​

VariableDescriptionDefault
SERVER_PORTGateway port8761
EUREKA_SERVER_URLEureka server URLhttp://localhost:8761/eureka/
GATEWAY_ROUTES_*Custom route configurations-

application.yml​

server:
  port: 8761

spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
          lower-case-service-id: true

eureka:
  client:
    register-with-eureka: false
    fetch-registry: false
  server:
    enable-self-preservation: false

Architecture​

The API Gateway follows a reactive architecture pattern:

  1. Request Reception: Incoming HTTP requests arrive at the gateway
  2. Service Discovery: Gateway queries Eureka for service location
  3. Load Balancing: Distributes requests across available instances
  4. Routing: Forwards request to target service
  5. Response: Returns service response to client

Integration with Rippler Services​

graph TB
    Client[Client/UI] --> Gateway[API Gateway]
    Gateway --> Eureka[Eureka Registry]
    Gateway --> WH[Webhook Handler]
    Gateway --> LLM[LLM Service]
    Gateway --> DG[Dependency Graph]
    Gateway --> NS[Notification Service]

Development​

Running Locally​

# Run with Maven
mvn spring-boot:run

# Run with Docker
docker build -t rippler-api-gateway .
docker run -p 8761:8761 rippler-api-gateway

Running in Rippler Stack​

# From project root
make up

# Or run with dependencies only
make dev-api-gateway

Troubleshooting​

Service Not Registering​

  1. Verify Eureka URL is correct
  2. Check network connectivity
  3. Ensure service has @EnableEurekaClient annotation
  4. Review service logs for errors

Routes Not Working​

  1. Check service is registered: GET /api/services
  2. Verify route configuration: GET /actuator/gateway/routes
  3. Check service health: GET /actuator/health
  4. Review gateway logs

Repository​

GitHub: rippler-api-gateway