Microservice Orchestration Demo

Problem Statement

Create a three-service microservice architecture demonstrating:

• Service Orchestration: Service 1 coordinates calls to Services 2 & 3
• REST API Communication: GET and POST endpoint interactions
• Distributed Tracing: Unique trace IDs for request flow tracking
• Error Handling: JSON validation and exception management
• API Documentation: Swagger UI integration

Solution Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    REQUEST FLOW DIAGRAM                         │
└─────────────────────────────────────────────────────────────────┘

    Client Request
         │
         ▼
┌─────────────────┐  [TraceID: abc123]
│   Service 1     │  
│  Orchestrator   │  GET /health → "Up"
│   Port 8080     │  POST /process → Orchestrates calls
│                 │  
│ ✓ Health Check  │  
│ ✓ Swagger UI    │  
│ ✓ Validation    │  
└─────────┬───────┘  
          │
          ├─────────────────────┬───────────────────────┐
          │ [TraceID: abc123]   │ [TraceID: abc123]     │
          ▼                     ▼                       │
┌─────────────────┐    ┌─────────────────┐              │
│   Service 2     │    │   Service 3     │              │
│  Hello Service  │    │  Name Service   │              │
│   Port 8081     │    │   Port 8082     │              │
│                 │    │                 │              │
│ GET /hello      │    │ POST /name      │              │
│ Returns:        │    │ Logs JSON       │              │
│ "Hello"         │    │ Returns:        │              │
│                 │    │ "John Doe"      │              │
└─────────┬───────┘    └─────────┬───────┘              │
          │                      │                      │
          └──────────┬───────────┘                      │
                     ▼                                  │
            ┌─────────────────┐                         │
            │ Combined Result │◄────────────────────────┘
            │ "Hello John Doe"│
            └─────────────────┘

Spring Boot Best Practices Applied

• Layered Architecture: Controller → Service → External API
• DTO Pattern: Request/response objects with validation
• Configuration Management: Externalized YAML properties
• Structured Logging: SLF4J with trace ID correlation
• Exception Handling: Global error handling with proper HTTP codes
• Modern HTTP Client: RestClient (Spring 6.1+)
• Resilience Patterns: Circuit Breaker, Retry, Rate Limiter with Resilience4j
• Production Ready: Actuator health checks, metrics, and monitoring endpoints

API Endpoints

Service 1 - Orchestrator (Port 8080)

Method	Endpoint	Description	Response
GET	/api/v1/orchestrator/health	Health check	"Up"
POST	/api/v1/orchestrator/process	Process person data	"Hello John Doe"

Service 2 - Hello Service (Port 8081)

Method	Endpoint	Description	Response
GET	/api/v1/hello	Get greeting	"Hello"

Service 3 - Name Service (Port 8082)

Method	Endpoint	Description	Response
POST	/api/v1/name	Process name	"John Doe"

Technology Stack

• Spring Boot 3.2.0
• Java 17
• Maven
• OpenAPI 3 (Swagger)
• Bean Validation
• SLF4J Logging
• Spring Boot Actuator (Health & Metrics)

Quick Start

Prerequisites

• Java 17+
• Maven 3.6+

Running Services

# Start services in order
cd service2-hello && mvn spring-boot:run
cd service3-name && mvn spring-boot:run  
cd service1-orchestrator && mvn spring-boot:run

Testing

# Health check
curl http://localhost:8080/api/v1/orchestrator/health

# Process request
curl -X POST http://localhost:8080/api/v1/orchestrator/process \
  -H "Content-Type: application/json" \
  -d '{"Name":"John","Surname":"Doe"}'

API Documentation

Swagger UI Access:

• Service 1: http://localhost:8080/swagger-ui.html
• Service 2: http://localhost:8081/swagger-ui.html
• Service 3: http://localhost:8082/swagger-ui.html

Request/Response Flow

Input JSON:

{
  "Name": "John",
  "Surname": "Doe"
}

Service Flow:

1. Service 1 receives POST request
2. Service 1 → Service 2: GET /hello → Returns "Hello"
3. Service 1 → Service 3: POST /name → Logs JSON → Returns "John Doe"
4. Service 1 combines responses → "Hello John Doe"

Final Output:

"Hello John Doe"

Error Response (Invalid JSON):

{
  "timestamp": "2024-01-15T10:30:45Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Name: Name is required, Surname: Surname is required",
  "traceId": "abc123"
}

Distributed Tracing Implementation

Trace ID Flow:

Request → TraceFilter → MDC → Service Logs → Response Headers

Log Output Example:

2024-01-15 10:30:45 [http-nio-8080-exec-1] INFO [abc123] Process method called with name=John surname=Doe
2024-01-15 10:30:45 [http-nio-8080-exec-1] INFO [abc123] Calling Hello service at http://localhost:8081/api/v1/hello
2024-01-15 10:30:45 [http-nio-8081-exec-1] INFO [abc123] Hello method called
2024-01-15 10:30:45 [http-nio-8080-exec-1] INFO [abc123] Calling Name service at http://localhost:8082/api/v1/name
2024-01-15 10:30:45 [http-nio-8082-exec-1] INFO [abc123] Processing name request: PersonRequest(name=John, surname=Doe)
2024-01-15 10:30:45 [http-nio-8080-exec-1] INFO [abc123] Process completed successfully with greeting: Hello John Doe

Project Structure

Task1/
├── service1-orchestrator/
│   ├── src/main/java/com/microservice/orchestrator/
│   └── pom.xml
├── service2-hello/
│   ├── src/main/java/com/microservice/hello/
│   └── pom.xml
└── service3-name/
    ├── src/main/java/com/microservice/name/
    └── pom.xml

Key Implementation Details

Error Handling:

• @Valid annotation with Bean Validation
• GlobalExceptionHandler for consistent error responses
• HTTP status codes: 400 (validation), 502 (downstream), 500 (server)

Tracing:

• TraceFilter generates/propagates trace IDs
• MDC for thread-local trace context
• Headers: X-Trace-ID for cross-service correlation

Configuration:

• Externalized service URLs in application.yml
• Type-safe @ConfigurationProperties
• Environment-specific configurations

Testing & Validation

**Manual Testing:**

```bash
# Health Check
curl http://localhost:8080/api/v1/orchestrator/health

# Valid Request
curl -X POST http://localhost:8080/api/v1/orchestrator/process \
  -H "Content-Type: application/json" \
  -d '{"Name":"John","Surname":"Doe"}'

# Invalid Request (Missing fields)
curl -X POST http://localhost:8080/api/v1/orchestrator/process \
  -H "Content-Type: application/json" \
  -d '{"Name":""}'

Expected Results:

• Health: {"status":"Up","traceId":"...","timestamp":"..."}
• Valid: {"greeting":"Hello John Doe","traceId":"..."}
• Invalid: {"status":400,"message":"Name: Name is required",...}